diff --git a/.markdownlint.json b/.markdownlint.json index 6306b80bad9c..edb9ba823cd7 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -6,6 +6,7 @@ "MD024": { "siblings_only": true }, "MD025": false, "MD033": false, + "MD034": false, "no-hard-tabs": false, "whitespace": false } \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index ba46ff4f05c9..b9815b669281 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1665,7 +1665,7 @@ that error is that the account doesn't exist. * Added a `ModuleAccount` for the mint module [\#4472](https://github.com/cosmos/cosmos-sdk/issues/4472) validation for crisis genesis * [\#3985](https://github.com/cosmos/cosmos-sdk/issues/3985) `ValidatorPowerRank` uses potential consensus power instead of tendermint power -* [\#4104](https://github.com/cosmos/cosmos-sdk/issues/4104) Gaia has been moved to its own repository: +* [\#4104](https://github.com/cosmos/cosmos-sdk/issues/4104) Gaia has been moved to its own repository: https://github.com/cosmos/gaia * [\#4104](https://github.com/cosmos/cosmos-sdk/issues/4104) Rename gaiad.toml to app.toml. The internal contents of the application config remain unchanged. * [\#4159](https://github.com/cosmos/cosmos-sdk/issues/4159) create the default module patterns and module manager @@ -2427,7 +2427,7 @@ BUG FIXES * Gaia CLI (`gaiacli`) * [\#3417](https://github.com/cosmos/cosmos-sdk/pull/3417) Fix `q slashing signing-info` panic by ensuring safety of user input and properly returning not found error * [\#3345](https://github.com/cosmos/cosmos-sdk/issues/3345) Upgrade ledger-cosmos-go dependency to v0.9.3 to pull - in order to fix a derivation path issue that causes `gaiacli keys add --recover` + https://github.com/ZondaX/ledger-cosmos-go/commit/ed9aa39ce8df31bad1448c72d3d226bf2cb1a8d1 in order to fix a derivation path issue that causes `gaiacli keys add --recover` to malfunction. * [\#3419](https://github.com/cosmos/cosmos-sdk/pull/3419) Fix `q distr slashes` panic * [\#3453](https://github.com/cosmos/cosmos-sdk/pull/3453) The `rest-server` command didn't respect persistent flags such as `--chain-id` and `--trust-node` if they were @@ -2464,7 +2464,7 @@ BREAKING CHANGES * [\#3320](https://github.com/cosmos/cosmos-sdk/pull/3320) Ensure all `gaiacli query` commands respect the `--output` and `--indent` flags * Gaia - * - Move store keys to constants + * https://github.com/cosmos/cosmos-sdk/issues/2838 - Move store keys to constants * [\#3162](https://github.com/cosmos/cosmos-sdk/issues/3162) The `--gas` flag now takes `auto` instead of `simulate` in order to trigger a simulation of the tx before the actual execution. * [\#3285](https://github.com/cosmos/cosmos-sdk/pull/3285) New `gaiad tendermint version` to print libs versions @@ -3097,7 +3097,7 @@ BUG FIXES * [docs] Fixed light client section links * SDK - * [\#1988](https://github.com/cosmos/cosmos-sdk/issues/1988) Make us compile on OpenBSD (disable ledger) [#1988] () + * [\#1988](https://github.com/cosmos/cosmos-sdk/issues/1988) Make us compile on OpenBSD (disable ledger) * [\#2105](https://github.com/cosmos/cosmos-sdk/issues/2105) Fix DB Iterator leak, which may leak a go routine. * [ledger] [\#2064](https://github.com/cosmos/cosmos-sdk/issues/2064) Fix inability to sign and send transactions via the LCD by loading a Ledger device at runtime. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d0619eac1d4c..7c2621f9b310 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -207,7 +207,7 @@ For example, in vscode your `.vscode/settings.json` should look like: ## Branching Model and Release -User-facing repos should adhere to the trunk based development branching model: . User branches should start with a user name, example: `{moniker}/{issue#}-branch-name`. +User-facing repos should adhere to the trunk based development branching model: https://trunkbaseddevelopment.com. User branches should start with a user name, example: `{moniker}/{issue#}-branch-name`. The Cosmos SDK repository is a [multi Go module](https://github.com/golang/go/wiki/Modules#is-it-possible-to-add-a-module-to-a-multi-module-repository) repository. It means that we have more than one Go module in a single repository. diff --git a/cosmovisor/RELEASE_NOTES.md b/cosmovisor/RELEASE_NOTES.md index 123bf08f755a..95e1ddf9538f 100644 --- a/cosmovisor/RELEASE_NOTES.md +++ b/cosmovisor/RELEASE_NOTES.md @@ -3,10 +3,12 @@ ### New execution model With this release we are shifting to a new CLI design: + * in the past, Cosmovisor was designed to act as a wrapper for a Cosmos App. An admin could link it and use it instead of the Cosmos App. When running it will pass all options and configuration parameters to the app. Hence the only way to configure the Cosmovisor was through environment variables. * now, we are moving to a more traditional model, where Cosmovisor has it's own command set and is a true supervisor. New commands have been added: + * `run` will start the Cosmos App and pass remaining arguments to the app (similar to `npm run`) * `help` will display Cosmovisor help * `version` will display both Cosmovisor and the associated app version. diff --git a/crypto/keys/secp256k1/internal/secp256k1/README.md b/crypto/keys/secp256k1/internal/secp256k1/README.md index c999fb31be0c..3a558a130a93 100644 --- a/crypto/keys/secp256k1/internal/secp256k1/README.md +++ b/crypto/keys/secp256k1/internal/secp256k1/README.md @@ -1,5 +1,5 @@ # secp256k1 -This package is copied from +This package is copied from https://github.com/ethereum/go-ethereum/tree/729bf365b5f17325be9107b63b233da54100eec6/crypto/secp256k1 Unlike the rest of go-ethereum it is MIT licensed so compatible with our Apache2.0 license. We opt to copy in here rather than depend on go-ethereum to avoid issues with vendoring of the GPL parts of that repository by downstream. diff --git a/docs/DOCS_README.md b/docs/DOCS_README.md index 5e6af356bb64..9ec1fd81c1e5 100644 --- a/docs/DOCS_README.md +++ b/docs/DOCS_README.md @@ -19,7 +19,7 @@ If you want to open a PR in Cosmos SDK to update the documentation, please follo ## Docs Build Workflow -The documentation for Cosmos SDK is hosted at and built from the files in the `/docs` directory. +The documentation for Cosmos SDK is hosted at https://docs.cosmos.network/ and built from the files in the `/docs` directory. ### How It Works @@ -84,7 +84,7 @@ Install the theme and all dependencies. npm run serve ``` -Run `pre` and `post` hooks and start a hot-reloading web-server. See output of this command for the URL (it is often ). +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. diff --git a/docs/architecture/adr-002-docs-structure.md b/docs/architecture/adr-002-docs-structure.md index ba59ecd044b7..5819151fc1dc 100644 --- a/docs/architecture/adr-002-docs-structure.md +++ b/docs/architecture/adr-002-docs-structure.md @@ -70,7 +70,7 @@ Accepted * Developers only have to update `/docs` folder when they open a PR (and not `/examples` for example). * Easier for developers to find what they need to update in the docs thanks to reworked architecture. * Cleaner vuepress build for website docs. -* Will help build an executable doc (cf ) +* Will help build an executable doc (cf https://github.com/cosmos/cosmos-sdk/issues/2611) ### Neutral @@ -81,6 +81,6 @@ Accepted ## References -* -* -* +* https://github.com/cosmos/cosmos-sdk/issues/1460 +* https://github.com/cosmos/cosmos-sdk/pull/2695 +* https://github.com/cosmos/cosmos-sdk/issues/2611 diff --git a/docs/architecture/adr-004-split-denomination-keys.md b/docs/architecture/adr-004-split-denomination-keys.md index 5083e7bcb389..3012901b8d61 100644 --- a/docs/architecture/adr-004-split-denomination-keys.md +++ b/docs/architecture/adr-004-split-denomination-keys.md @@ -115,6 +115,6 @@ None in particular. ## References -* Ref: -* Ref: -* Ref: +* Ref: https://github.com/cosmos/cosmos-sdk/issues/4982 +* Ref: https://github.com/cosmos/cosmos-sdk/issues/5467 +* Ref: https://github.com/cosmos/cosmos-sdk/issues/5492 diff --git a/docs/architecture/adr-016-validator-consensus-key-rotation.md b/docs/architecture/adr-016-validator-consensus-key-rotation.md index 4ee797e55a8f..0510c2b9be79 100644 --- a/docs/architecture/adr-016-validator-consensus-key-rotation.md +++ b/docs/architecture/adr-016-validator-consensus-key-rotation.md @@ -7,7 +7,7 @@ ## Context -Validator consensus key rotation feature has been discussed and requested for a long time, for the sake of safer validator key management policy (e.g. ). So, we suggest one of the simplest form of validator consensus key rotation implementation mostly onto Cosmos SDK. +Validator consensus key rotation feature has been discussed and requested for a long time, for the sake of safer validator key management policy (e.g. https://github.com/tendermint/tendermint/issues/1136). So, we suggest one of the simplest form of validator consensus key rotation implementation mostly onto Cosmos SDK. We don't need to make any update on consensus logic in Tendermint because Tendermint does not have any mapping information of consensus key and validator operator key, meaning that from Tendermint point of view, a consensus key rotation of a validator is simply a replacement of a consensus key to another. @@ -109,7 +109,7 @@ Proposed ### Positive * Validators can immediately or periodically rotate their consensus key to have better security policy -* improved security against Long-Range attacks () given a validator throws away the old consensus key(s) +* improved security against Long-Range attacks (https://nearprotocol.com/blog/long-range-attacks-and-a-new-fork-choice-rule) given a validator throws away the old consensus key(s) ### Negative @@ -120,6 +120,6 @@ Proposed ## References -* on tendermint repo : -* on cosmos-sdk repo : -* about multiple consensus keys : +* on tendermint repo : https://github.com/tendermint/tendermint/issues/1136 +* on cosmos-sdk repo : https://github.com/cosmos/cosmos-sdk/issues/5231 +* about multiple consensus keys : https://github.com/tendermint/tendermint/issues/1758#issuecomment-545291698 diff --git a/docs/architecture/adr-019-protobuf-state-encoding.md b/docs/architecture/adr-019-protobuf-state-encoding.md index f8e05c7d0707..4f5f0b52ddbf 100644 --- a/docs/architecture/adr-019-protobuf-state-encoding.md +++ b/docs/architecture/adr-019-protobuf-state-encoding.md @@ -375,5 +375,5 @@ seamless. ## References -1. -2. +1. https://github.com/cosmos/cosmos-sdk/issues/4977 +2. https://github.com/cosmos/cosmos-sdk/issues/5444 diff --git a/docs/architecture/adr-020-protobuf-transaction-encoding.md b/docs/architecture/adr-020-protobuf-transaction-encoding.md index c28c71610dae..32ee3a64a6ab 100644 --- a/docs/architecture/adr-020-protobuf-transaction-encoding.md +++ b/docs/architecture/adr-020-protobuf-transaction-encoding.md @@ -270,7 +270,7 @@ processors because: not `TxBody`) There are also scenarios where we may choose to safely ignore unknown fields -() to +(https://github.com/cosmos/cosmos-sdk/issues/6078#issuecomment-624400188) to provide graceful forwards compatibility with newer clients. We propose that field numbers with bit 11 set (for most use cases this is @@ -379,7 +379,7 @@ can gracefully transition away from Amino JSON. ### `SIGN_MODE_DIRECT_AUX` -(\*Documented as option (3) in ) +(\*Documented as option (3) in https://github.com/cosmos/cosmos-sdk/issues/6078#issuecomment-628026933) We could add a mode `SIGN_MODE_DIRECT_AUX` to support scenarios where multiple signatures @@ -437,7 +437,7 @@ To generate a signature in `SIGN_MODE_DIRECT_AUX` these steps would be followed: ### `SIGN_MODE_DIRECT_RELAXED` -(_Documented as option (1)(a) in _) +(_Documented as option (1)(a) in https://github.com/cosmos/cosmos-sdk/issues/6078#issuecomment-628026933_) This is a variation of `SIGN_MODE_DIRECT` where multiple signers wouldn't need to coordinate public keys and signing modes in advance. It would involve an alternate diff --git a/docs/architecture/adr-027-deterministic-protobuf-serialization.md b/docs/architecture/adr-027-deterministic-protobuf-serialization.md index 8a20435a3f04..e75b142001c5 100644 --- a/docs/architecture/adr-027-deterministic-protobuf-serialization.md +++ b/docs/architecture/adr-027-deterministic-protobuf-serialization.md @@ -260,7 +260,7 @@ for all protobuf documents we need in the context of Cosmos SDK signing. * Simple enough to keep the barrier to implement transaction signing low * It allows us to continue to use 0 and other empty values in SignDoc, avoiding the need to work around 0 sequences. This does not imply the change from - should not be merged, but not + https://github.com/cosmos/cosmos-sdk/pull/6949 should not be merged, but not too important anymore. ### Negative @@ -288,27 +288,27 @@ the need of implementing a custom serializer that adheres to this standard (and implementation detail and the details of any particular implementation may change in the future. Therefore, protocol buffer parsers must be able to parse fields in any order._ from - -* 2 + https://developers.google.com/protocol-buffers/docs/encoding#order +* 2 https://developers.google.com/protocol-buffers/docs/encoding#signed_integers * 3 _Note that for scalar message fields, once a message is parsed there's no way of telling whether a field was explicitly set to the default value (for example whether a boolean was set to false) or just not set at all: you should bear this in mind when defining your message types. For example, don't have a boolean that switches on some behavior when set to false if you don't want that behavior to also happen by default._ from - + https://developers.google.com/protocol-buffers/docs/proto3#default * 4 _When a message is parsed, if the encoded message does not contain a particular singular element, the corresponding field in the parsed object is set to the default value for that field._ from - + https://developers.google.com/protocol-buffers/docs/proto3#default * 5 _Also note that if a scalar message field is set to its default, the value will not be serialized on the wire._ from - + https://developers.google.com/protocol-buffers/docs/proto3#default * 6 _For enums, the default value is the first defined enum value, which must be 0._ from - + https://developers.google.com/protocol-buffers/docs/proto3#default * 7 _For message fields, the field is not set. Its exact value is language-dependent._ from - + https://developers.google.com/protocol-buffers/docs/proto3#default * Encoding rules and parts of the reasoning taken from [canonical-proto3 Aaron Craelius](https://github.com/regen-network/canonical-proto3) diff --git a/docs/architecture/adr-028-public-key-addresses.md b/docs/architecture/adr-028-public-key-addresses.md index 9cf49f8db007..8da5b70d0f2e 100644 --- a/docs/architecture/adr-028-public-key-addresses.md +++ b/docs/architecture/adr-028-public-key-addresses.md @@ -29,12 +29,12 @@ a security break of one account type shouldn't impact the security of other acco One initial proposal was extending the address length and adding prefixes for different types of addresses. -@ethanfrey explained an alternate approach originally used in : +@ethanfrey explained an alternate approach originally used in https://github.com/iov-one/weave: > I spent quite a bit of time thinking about this issue while building weave... The other cosmos Sdk. > Basically I define a condition to be a type and format as human readable string with some binary data appended. This condition is hashed into an Address (again at 20 bytes). The use of this prefix makes it impossible to find a preimage for a given address with a different condition (eg ed25519 vs secp256k1). -> This is explained in depth here -> And the code is here, look mainly at the top where we process conditions. +> This is explained in depth here https://weave.readthedocs.io/en/latest/design/permissions.html +> And the code is here, look mainly at the top where we process conditions. https://github.com/iov-one/weave/blob/master/conditions.go And explained how this approach should be sufficiently collision resistant: @@ -60,7 +60,7 @@ In the issue we discussed various modifications: ### Requirements -* Support currently used tools - we don't want to break an ecosystem, or add a long adaptation period. Ref: +* Support currently used tools - we don't want to break an ecosystem, or add a long adaptation period. Ref: https://github.com/cosmos/cosmos-sdk/issues/8041 * Try to keep the address length small - addresses are widely used in state, both as part of a key and object value. ### Scope diff --git a/docs/architecture/adr-029-fee-grant-module.md b/docs/architecture/adr-029-fee-grant-module.md index c2799c476a2a..5e026d604305 100644 --- a/docs/architecture/adr-029-fee-grant-module.md +++ b/docs/architecture/adr-029-fee-grant-module.md @@ -148,6 +148,6 @@ created to use it ## References -* Blog article describing initial work: -* Initial public specification: -* Original subkeys proposal from B-harvest which influenced this design: +* Blog article describing initial work: https://medium.com/regen-network/hacking-the-cosmos-cosmwasm-and-key-management-a08b9f561d1b +* Initial public specification: https://gist.github.com/aaronc/b60628017352df5983791cad30babe56 +* Original subkeys proposal from B-harvest which influenced this design: https://github.com/cosmos/cosmos-sdk/issues/4480 diff --git a/docs/architecture/adr-030-authz-module.md b/docs/architecture/adr-030-authz-module.md index 62ba1885ccaf..0bdf08ecb6c0 100644 --- a/docs/architecture/adr-030-authz-module.md +++ b/docs/architecture/adr-030-authz-module.md @@ -244,6 +244,6 @@ SDK users ## References -* Initial Hackatom implementation: -* Post-Hackatom spec: -* B-Harvest subkeys spec: +* Initial Hackatom implementation: https://github.com/cosmos-gaians/cosmos-sdk/tree/hackatom/x/delegation +* Post-Hackatom spec: https://gist.github.com/aaronc/b60628017352df5983791cad30babe56#delegation-module +* B-Harvest subkeys spec: https://github.com/cosmos/cosmos-sdk/issues/4480 diff --git a/docs/architecture/adr-031-msg-service.md b/docs/architecture/adr-031-msg-service.md index eabf243d2591..0fcc6b4df642 100644 --- a/docs/architecture/adr-031-msg-service.md +++ b/docs/architecture/adr-031-msg-service.md @@ -41,7 +41,7 @@ This isn’t really documented anywhere and clients would need to know the inter of the Cosmos SDK to parse that value and return it to users. Also, there may be cases where we want to use these return values programatically. -For instance, proposes a method for +For instance, https://github.com/cosmos/cosmos-sdk/issues/7093 proposes a method for doing inter-module Ocaps using the `Msg` router. A well-defined return type would improve the developer UX for this approach. diff --git a/docs/architecture/adr-034-account-rekeying.md b/docs/architecture/adr-034-account-rekeying.md index 21eaff0f6733..cd9b91469c42 100644 --- a/docs/architecture/adr-034-account-rekeying.md +++ b/docs/architecture/adr-034-account-rekeying.md @@ -73,4 +73,4 @@ Breaks the current assumed relationship between address and pubkeys as H(pubkey) ## References -* +* https://www.algorand.com/resources/blog/announcing-rekeying diff --git a/docs/architecture/adr-035-rosetta-api-support.md b/docs/architecture/adr-035-rosetta-api-support.md index 5e8d300136b0..01a81048bf95 100644 --- a/docs/architecture/adr-035-rosetta-api-support.md +++ b/docs/architecture/adr-035-rosetta-api-support.md @@ -208,4 +208,4 @@ Proposed ## References -* +* https://www.rosetta-api.org/ diff --git a/docs/architecture/adr-036-arbitrary-signature.md b/docs/architecture/adr-036-arbitrary-signature.md index c82ca6459485..d40929452e1c 100644 --- a/docs/architecture/adr-036-arbitrary-signature.md +++ b/docs/architecture/adr-036-arbitrary-signature.md @@ -126,7 +126,7 @@ Backwards compatibility is maintained as this is a new message spec definition. ## References -1. -2. -3. -4. +1. https://github.com/cosmos/ics/pull/33 +2. https://github.com/cosmos/cosmos-sdk/pull/7727#discussion_r515668204 +3. https://github.com/cosmos/cosmos-sdk/pull/7727#issuecomment-722478477 +4. https://github.com/cosmos/cosmos-sdk/pull/7727#issuecomment-721062923 diff --git a/docs/architecture/adr-039-epoched-staking.md b/docs/architecture/adr-039-epoched-staking.md index 8c227e586927..29418fc896e5 100644 --- a/docs/architecture/adr-039-epoched-staking.md +++ b/docs/architecture/adr-039-epoched-staking.md @@ -44,7 +44,7 @@ There is a design consideration for whether to apply a slash immediately or at t Applying it immediately can be viewed as offering greater consensus layer security, at potential costs to the aforementioned usecases. The benefits of immediate slashing for consensus layer security can be all be obtained by executing the validator jailing immediately (thus removing it from the validator set), and delaying the actual slash change to the validator's weight until the epoch boundary. For the use cases mentioned above, workarounds can be integrated to avoid problems, as follows: * For threshold based cryptography, this setting will have the threshold cryptography use the original epoch weights, while consensus has an update that lets it more rapidly benefit from additional security. If the threshold based cryptography blocks liveness of the chain, then we have effectively raised the liveness threshold of the remaining validators for the rest of the epoch. (Alternatively, jailed nodes could still contribute shares) This plan will fail in the extreme case that more than 1/3rd of the validators have been jailed within a single epoch. For such an extreme scenario, the chain already have its own custom incident response plan, and defining how to handle the threshold cryptography should be a part of that. -* For light client efficiency, there can be a bit included in the header indicating an intra-epoch slash (ala ). +* For light client efficiency, there can be a bit included in the header indicating an intra-epoch slash (ala https://github.com/tendermint/spec/issues/199). * For fairness of deterministic leader election, applying a slash or jailing within an epoch would break the guarantee we were seeking to provide. This then re-introduces a new (but significantly simpler) problem for trying to provide fairness guarantees. Namely, that validators can adversarially elect to remove themself from the set of proposers. From a security perspective, this could potentially be handled by two different mechanisms (or prove to still be too difficult to achieve). One is making a security statement acknowledging the ability for an adversary to force an ahead-of-time fixed threshold of users to drop out of the proposer set within an epoch. The second method would be to parameterize such that the cost of a slash within the epoch far outweights benefits due to being a proposer. However, this latter criterion is quite dubious, since being a proposer can have many advantageous side-effects in chains with complex state machines. (Namely, DeFi games such as Fomo3D) * For staking derivative design, there is no issue introduced. This does not increase the state size of staking records, since whether a slash has occured is fully queryable given the validator address. diff --git a/docs/architecture/adr-041-in-place-store-migrations.md b/docs/architecture/adr-041-in-place-store-migrations.md index 9366f1af4a11..b0ff8e4e711c 100644 --- a/docs/architecture/adr-041-in-place-store-migrations.md +++ b/docs/architecture/adr-041-in-place-store-migrations.md @@ -162,6 +162,6 @@ While modules MUST register their migration functions when bumping ConsensusVers ## References -* Initial discussion: -* Implementation of `ConsensusVersion` and `RunMigrations`: -* Issue discussing `x/upgrade` design: +* Initial discussion: https://github.com/cosmos/cosmos-sdk/discussions/8429 +* Implementation of `ConsensusVersion` and `RunMigrations`: https://github.com/cosmos/cosmos-sdk/pull/8485 +* Issue discussing `x/upgrade` design: https://github.com/cosmos/cosmos-sdk/issues/8514 diff --git a/docs/architecture/adr-042-group-module.md b/docs/architecture/adr-042-group-module.md index bf24b3effa83..74ba17f436ae 100644 --- a/docs/architecture/adr-042-group-module.md +++ b/docs/architecture/adr-042-group-module.md @@ -24,7 +24,7 @@ The legacy amino multi-signature mechanism of the Cosmos SDK has certain limitat While the group module is not meant to be a total replacement for the current multi-signature accounts, it provides a solution to the limitations described above, with a more flexible key management system where keys can be added, updated or removed, as well as configurable thresholds. It's meant to be used with other access control modules such as [`x/feegrant`](./adr-029-fee-grant-module.md) ans [`x/authz`](adr-030-authz-module.md) to simplify key management for individuals and organizations. -The proof of concept of the group module can be found in and . +The proof of concept of the group module can be found in https://github.com/regen-network/regen-ledger/tree/master/proto/regen/group/v1alpha1 and https://github.com/regen-network/regen-ledger/tree/master/x/group. ## Decision @@ -265,15 +265,15 @@ Inter-module communication introduced by [ADR-033](adr-033-protobuf-inter-module ## Further Discussions -* Convergence of `/group` and `x/gov` as both support proposals and voting: +* Convergence of `/group` and `x/gov` as both support proposals and voting: https://github.com/cosmos/cosmos-sdk/discussions/9066 * `x/group` possible future improvements: - * Execute proposals on submission () - * Withdraw a proposal () + * Execute proposals on submission (https://github.com/regen-network/regen-ledger/issues/288) + * Withdraw a proposal (https://github.com/regen-network/cosmos-modules/issues/41) * Make `Tally` more flexible and support non-binary choices ## References * Initial specification: - * + * https://gist.github.com/aaronc/b60628017352df5983791cad30babe56#group-module * [#5236](https://github.com/cosmos/cosmos-sdk/pull/5236) * Proposal to add `x/group` into the Cosmos SDK: [#7633](https://github.com/cosmos/cosmos-sdk/issues/7633) diff --git a/docs/architecture/adr-043-nft-module.md b/docs/architecture/adr-043-nft-module.md index 802d2d03a949..2779ff2deb8e 100644 --- a/docs/architecture/adr-043-nft-module.md +++ b/docs/architecture/adr-043-nft-module.md @@ -21,7 +21,7 @@ This ADR defines the `x/nft` module which is a generic implementation of NFTs, r ## Context -NFTs are more than just crypto art, which is very helpful for accruing value to the Cosmos ecosystem. As a result, Cosmos Hub should implement NFT functions and enable a unified mechanism for storing and sending the ownership representative of NFTs as discussed in . +NFTs are more than just crypto art, which is very helpful for accruing value to the Cosmos ecosystem. As a result, Cosmos Hub should implement NFT functions and enable a unified mechanism for storing and sending the ownership representative of NFTs as discussed in https://github.com/cosmos/cosmos-sdk/discussions/9065. As discussed in [#9065](https://github.com/cosmos/cosmos-sdk/discussions/9065), several potential solutions can be considered: @@ -335,6 +335,6 @@ Other networks in the Cosmos ecosystem could design and implement their own NFT ## References -* Initial discussion: -* x/nft: initialize module: +* Initial discussion: https://github.com/cosmos/cosmos-sdk/discussions/9065 +* x/nft: initialize module: https://github.com/cosmos/cosmos-sdk/pull/9174 * [ADR 033](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-033-protobuf-inter-module-comm.md) diff --git a/docs/architecture/adr-045-check-delivertx-middlewares.md b/docs/architecture/adr-045-check-delivertx-middlewares.md index b8c1ad3a7c62..bb108d401ea4 100644 --- a/docs/architecture/adr-045-check-delivertx-middlewares.md +++ b/docs/architecture/adr-045-check-delivertx-middlewares.md @@ -307,5 +307,5 @@ For new middlewares, we introduce unit tests. Since middlewares are purposefully ## References -* Initial discussion: +* Initial discussion: https://github.com/cosmos/cosmos-sdk/issues/9585 * Implementation: [#9920 BaseApp refactor](https://github.com/cosmos/cosmos-sdk/pull/9920) and [#10028 Antehandlers migration](https://github.com/cosmos/cosmos-sdk/pull/10028) diff --git a/docs/architecture/adr-046-module-params.md b/docs/architecture/adr-046-module-params.md index 7c378adeee8d..6c068e4e0107 100644 --- a/docs/architecture/adr-046-module-params.md +++ b/docs/architecture/adr-046-module-params.md @@ -179,6 +179,6 @@ Later, this section can optionally list ideas or improvements the author or revi ## References -* -* -* +* https://github.com/cosmos/cosmos-sdk/pull/9810 +* https://github.com/cosmos/cosmos-sdk/issues/9438 +* https://github.com/cosmos/cosmos-sdk/discussions/9913 diff --git a/docs/basics/accounts.md b/docs/basics/accounts.md index c97dacbdd488..05e9ff268141 100644 --- a/docs/basics/accounts.md +++ b/docs/basics/accounts.md @@ -88,7 +88,7 @@ Each account is identified using `Address` which is a sequence of bytes derived These types implement the `Address` interface: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/address.go#L71-L90 Address construction algorithm is defined in [ADR-28](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-028-public-key-addresses.md). Here is the standard way to obtain an account address from a `pub` public key: @@ -101,7 +101,7 @@ Of note, the `Marshal()` and `Bytes()` method both return the same raw `[]byte` For user interaction, addresses are formatted using [Bech32](https://en.bitcoin.it/wiki/Bech32) and implemented by the `String` method. The Bech32 method is the only supported format to use when interacting with a blockchain. The Bech32 human-readable part (Bech32 prefix) is used to denote an address type. Example: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/address.go#L230-L244 | | Address Bech32 Prefix | | ------------------ | --------------------- | @@ -113,7 +113,7 @@ For user interaction, addresses are formatted using [Bech32](https://en.bitcoin. Public keys in Cosmos SDK are defined by `cryptotypes.PubKey` interface. Since public keys are saved in a store, `cryptotypes.PubKey` extends the `proto.Message` interface: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/types/types.go#L8-L17 A compressed format is used for `secp256k1` and `secp256r1` serialization. @@ -125,20 +125,20 @@ This prefix is followed by the `x`-coordinate. Public Keys are not used to reference accounts (or users) and in general are not used when composing transaction messages (with few exceptions: `MsgCreateValidator`, `Validator` and `Multisig` messages). For user interactions, `PubKey` is formatted using Protobufs JSON ([ProtoMarshalJSON](https://github.com/cosmos/cosmos-sdk/blob/release/v0.42.x/codec/json.go#L12) function). Example: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/7568b66/crypto/keyring/output.go#L23-L39 ## Keyring A `Keyring` is an object that stores and manages accounts. In the Cosmos SDK, a `Keyring` implementation follows the `Keyring` interface: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/keyring/keyring.go#L51-L89 The default implementation of `Keyring` comes from the third-party [`99designs/keyring`](https://github.com/99designs/keyring) library. A few notes on the `Keyring` methods: * `Sign(uid string, payload []byte) ([]byte, sdkcrypto.PubKey, error)` strictly deals with the signature of the `payload` bytes. You must prepare and encode the transaction into a canonical `[]byte` form. Because protobuf is not deterministic, it has been decided in [ADR-020](../architecture/adr-020-protobuf-transaction-encoding.md) that the canonical `payload` to sign is the `SignDoc` struct, deterministically encoded using [ADR-027](../architecture/adr-027-deterministic-protobuf-serialization.md). Note that signature verification is not implemented in the Cosmos SDK by default, it is deferred to the [`anteHandler`](../core/baseapp.md#antehandler). - +++ + +++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/proto/cosmos/tx/v1beta1/tx.proto#L47-L64 * `NewAccount(uid, mnemonic, bip39Passwd, hdPath string, algo SignatureAlgo) (Info, error)` creates a new account based on the [`bip44 path`](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) and persists it on disk. The `PrivKey` is **never stored unencrypted**, instead it is [encrypted with a passphrase](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/crypto/armor.go) before being persisted. In the context of this method, the key type and sequence number refer to the segment of the BIP44 derivation path (for example, `0`, `1`, `2`, ...) that is used to derive a private and a public key from the mnemonic. Using the same mnemonic and derivation path, the same `PrivKey`, `PubKey` and `Address` is generated. The following keys are supported by the keyring: diff --git a/docs/basics/app-anatomy.md b/docs/basics/app-anatomy.md index ab6f34e99b53..f5ea9160b558 100644 --- a/docs/basics/app-anatomy.md +++ b/docs/basics/app-anatomy.md @@ -53,13 +53,13 @@ The first thing defined in `app.go` is the `type` of the application. It is gene See an example of application type definition from `simapp`, the Cosmos SDK's own app used for demo and testing purposes: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L145-L187 ### Constructor Function This function constructs a new application of the type defined in the section above. It must fulfill the `AppCreator` signature in order to be used in the [`start` command](../core/node.md#start-command) of the application's daemon command. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/types/app.go#L48-L50 Here are the main actions performed by this function: @@ -81,7 +81,7 @@ Note that this function only creates an instance of the app, while the actual st See an example of application constructor from `simapp`: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L198-L441 ### InitChainer @@ -91,7 +91,7 @@ In general, the `InitChainer` is mostly composed of the [`InitGenesis`](../build See an example of an `InitChainer` from `simapp`: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L464-L471 ### BeginBlocker and EndBlocker @@ -103,13 +103,13 @@ As a sidenote, it is important to remember that application-specific blockchains See an example of `BeginBlocker` and `EndBlocker` functions from `simapp` -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/app.go#L454-L462 ### Register Codec The `EncodingConfig` structure is the last important part of the `app.go` file. The goal of this structure is to define the codecs that will be used throughout the app. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/params/encoding.go#L9-L16 Here are descriptions of what each of the four fields means: @@ -125,7 +125,7 @@ NOTE: this function is marked deprecated and should only be used to create an ap See an example of a `MakeTestEncodingConfig` from `simapp`: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/590358652cc1cbc13872ea1659187e073ea38e75/simapp/encoding.go#L8-L19 ## Modules @@ -154,7 +154,7 @@ For a more details look at a transaction [lifecycle](./tx-lifecycle.md). Module developers create custom `Msg` services when they build their own module. The general practice is to define the `Msg` Protobuf service in a `tx.proto` file. For example, the `x/bank` module defines a service with two methods to transfer tokens: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/bank/v1beta1/tx.proto#L10-L17 Service methods use `keeper` in order to update the module state. @@ -224,7 +224,7 @@ The main interface is the [Command-Line Interface](../core/cli.md). The CLI of a See an example of an application's main command-line file from the [nameservice tutorial](https://github.com/cosmos/sdk-tutorials/tree/master/nameservice) -+++ ++++ https://github.com/cosmos/sdk-tutorials/blob/86a27321cf89cc637581762e953d0c07f8c78ece/nameservice/cmd/nscli/main.go ## Dependencies and Makefile @@ -242,11 +242,11 @@ Please see [issue #8392](https://github.com/cosmos/cosmos-sdk/issues/8392) for m This section is optional, as developers are free to choose their dependency manager and project building method. That said, the current most used framework for versioning control is [`go.mod`](https://github.com/golang/go/wiki/Modules). It ensures each of the libraries used throughout the application are imported with the correct version. See an example from the [nameservice tutorial](https://github.com/cosmos/sdk-tutorials/tree/master/nameservice): -+++ ++++ https://github.com/cosmos/sdk-tutorials/blob/c6754a1e313eb1ed973c5c91dcc606f2fd288811/go.mod#L1-L18 For building the application, a [Makefile](https://en.wikipedia.org/wiki/Makefile) is generally used. The Makefile primarily ensures that the `go.mod` is run before building the two entrypoints to the application, [`appd`](#node-client) and [`appd`](#application-interface). See an example of Makefile from the [nameservice tutorial](https://tutorials.cosmos.network/nameservice/tutorial/00-intro.html) -+++ ++++ https://github.com/cosmos/sdk-tutorials/blob/86a27321cf89cc637581762e953d0c07f8c78ece/nameservice/Makefile ## Next {hide} diff --git a/docs/basics/gas-fees.md b/docs/basics/gas-fees.md index b4fdaae30ea2..81df8096e728 100644 --- a/docs/basics/gas-fees.md +++ b/docs/basics/gas-fees.md @@ -21,7 +21,7 @@ In the Cosmos SDK, `gas` is a special unit that is used to track the consumption In the Cosmos SDK, `gas` is a simple alias for `uint64`, and is managed by an object called a _gas meter_. Gas meters implement the `GasMeter` interface -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/store/types/gas.go#L34-L43 where: @@ -50,7 +50,7 @@ Gas consumption can be done manually, generally by the module developer in the [ `ctx.BlockGasMeter()` is the gas meter used to track gas consumption per block and make sure it does not go above a certain limit. A new instance of the `BlockGasMeter` is created each time [`BeginBlock`](../core/baseapp.md#beginblock) is called. The `BlockGasMeter` is finite, and the limit of gas per block is defined in the application's consensus parameters. By default Cosmos SDK applications use the default consensus parameters provided by Tendermint: -+++ ++++ https://github.com/tendermint/tendermint/blob/v0.34.0-rc6/types/params.go#L34-L41 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: @@ -74,9 +74,9 @@ type AnteHandler func(ctx Context, tx Tx, simulate bool) (newCtx Context, result The `anteHandler` is not implemented in the core Cosmos SDK but in a module. This gives the possibility to developers to choose which version of `AnteHandler` fits their application's needs. That said, most applications today use the default implementation defined in the [`auth` module](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth). Here is what the `anteHandler` is intended to do in a normal Cosmos SDK application: * Verify that the transaction are of the correct type. Transaction types are defined in the module that implements the `anteHandler`, and they follow the transaction interface: - +++ + +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/tx_msg.go#L49-L57 This enables developers to play with various types for the transaction of their application. In the default `auth` module, the default transaction type is `Tx`: - +++ + +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/tx.proto#L12-L25 * Verify signatures for each [`message`](../building-modules/messages-and-queries.md#messages) contained in the transaction. Each `message` should be signed by one or multiple sender(s), and these signatures must be verified in the `anteHandler`. * During `CheckTx`, verify that the gas prices provided with the transaction is greater than the local `min-gas-prices` (as a reminder, gas-prices can be deducted from the following equation: `fees = gas * gas-prices`). `min-gas-prices` is a parameter local to each full-node and used during `CheckTx` to discard transactions that do not provide a minimum amount of fees. This ensure that the mempool cannot be spammed with garbage transactions. * Verify that the sender of the transaction has enough funds to cover for the `fees`. When the end-user generates a transaction, they must indicate 2 of the 3 following parameters (the third one being implicit): `fees`, `gas` and `gas-prices`. This signals how much they are willing to pay for nodes to execute their transaction. The provided `gas` value is stored in a parameter called `GasWanted` for later use. diff --git a/docs/basics/query-lifecycle.md b/docs/basics/query-lifecycle.md index 0a0a85f5ee6f..7d85127d3827 100644 --- a/docs/basics/query-lifecycle.md +++ b/docs/basics/query-lifecycle.md @@ -91,7 +91,7 @@ The first thing that is created in the execution of a CLI command is a `client.C The `client.Context` also contains various functions such as `Query()` which retrieves the RPC Client and makes an ABCI call to relay a query to a full-node. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/context.go#L20-L50 The `client.Context`'s primary role is to store data used during interactions with the end-user and provide methods to interact with this data - it is used before and after the query is processed by the full-node. Specifically, in handling `MyQuery`, the `client.Context` is utilized to encode the query parameters, retrieve the full-node, and write the output. Prior to being relayed to a full-node, the query needs to be encoded into a `[]byte` form, as full-nodes are application-agnostic and do not understand specific types. The full-node (RPC Client) itself is retrieved using the `client.Context`, which knows which node the user CLI is connected to. The query is relayed to this full-node to be processed. Finally, the `client.Context` contains a `Writer` to write output when the response is returned. These steps are further described in later sections. @@ -105,19 +105,19 @@ In our case (querying an address's delegations), `MyQuery` contains an [address] Here is what the code looks like for the CLI command: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/staking/client/cli/query.go#L324-L327 #### gRPC Query Client Creation The Cosmos SDK leverages code generated from Protobuf services to make queries. The `staking` module's `MyQuery` service generates a `queryClient`, which the CLI will use to make queries. Here is the relevant code: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/x/staking/client/cli/query.go#L318-L342 Under the hood, the `client.Context` has a `Query()` function used to retrieve the pre-configured node and relay a query to it; the function takes the query fully-qualified service method name as path (in our case: `/cosmos.staking.v1beta1.Query/Delegations`), and arguments as parameters. It first retrieves the RPC Client (called the [**node**](../core/node.md)) configured by the user to relay this query to, and creates the `ABCIQueryOptions` (parameters formatted for the ABCI call). The node is then used to make the ABCI call, `ABCIQueryWithOptions()`. Here is what the code looks like: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/query.go#L65-L91 ## RPC @@ -143,7 +143,7 @@ Since `Query()` is an ABCI function, `baseapp` returns the response as an [`abci The application [`codec`](../core/encoding.md) is used to unmarshal the response to a JSON and the `client.Context` prints the output to the command line, applying any configurations such as the output type (text, JSON or YAML). -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/client/context.go#L248-L283 And that's a wrap! The result of the query is outputted to the console by the CLI. diff --git a/docs/building-modules/beginblock-endblock.md b/docs/building-modules/beginblock-endblock.md index 1e4497cdbf3f..2aab17db62f3 100644 --- a/docs/building-modules/beginblock-endblock.md +++ b/docs/building-modules/beginblock-endblock.md @@ -28,11 +28,11 @@ It is possible for developers to define the order of execution between the `Begi See an example implementation of `BeginBlocker` from the `distr` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/f33749263f4ecc796115ad6e789cb0f7cddf9148/x/distribution/abci.go#L14-L38 and an example implementation of `EndBlocker` from the `staking` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/f33749263f4ecc796115ad6e789cb0f7cddf9148/x/staking/abci.go#L22-L27 ## Next {hide} diff --git a/docs/building-modules/errors.md b/docs/building-modules/errors.md index fb846d1b7a3c..0a7990b7686c 100644 --- a/docs/building-modules/errors.md +++ b/docs/building-modules/errors.md @@ -18,7 +18,7 @@ of errors is handled via the `types/errors` package. Example: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0/x/distribution/types/errors.go#L1-L21 Each custom module error must provide the codespace, which is typically the module name (e.g. "distribution") and is unique per module, and a uint32 code. Together, the codespace and code @@ -38,7 +38,7 @@ execution. Example: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/b2d48a9e815fe534a7faeec6ca2adb0874252b81/x/bank/keeper/keeper.go#L85-L122 Regardless if an error is wrapped or not, the Cosmos SDK's `errors` package provides an API to determine if an error is of a particular kind via `Is`. diff --git a/docs/building-modules/genesis.md b/docs/building-modules/genesis.md index 92d456ec1264..f06115cc389e 100644 --- a/docs/building-modules/genesis.md +++ b/docs/building-modules/genesis.md @@ -17,7 +17,7 @@ The subset of the genesis state defined from a given module is generally defined See an example of `GenesisState` protobuf message definition from the `auth` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/a9547b54ffac9729fe1393651126ddfc0d236cff/proto/cosmos/auth/v1beta1/genesis.proto Next we present the main genesis-related methods that need to be implemented by module developers in order for their module to be used in Cosmos SDK applications. @@ -25,13 +25,13 @@ Next we present the main genesis-related methods that need to be implemented by The `DefaultGenesis()` method is a simple method that calls the constructor function for `GenesisState` with the default value for each parameter. See an example from the `auth` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/module.go#L48-L52 ### `ValidateGenesis` The `ValidateGenesis(genesisState GenesisState)` method is called to verify that the provided `genesisState` is correct. It should perform validity checks on each of the parameters listed in `GenesisState`. See an example from the `auth` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/types/genesis.go#L57-L70 ## Other Genesis Methods @@ -45,7 +45,7 @@ The [module manager](./module-manager.md#manager) of the application is responsi See an example of `InitGenesis` from the `auth` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/genesis.go#L13-L28 ### `ExportGenesis` @@ -53,7 +53,7 @@ The `ExportGenesis` method is executed whenever an export of the state is made. See an example of `ExportGenesis` from the `auth` module. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/64b6bb5270e1a3b688c2d98a8f481ae04bb713ca/x/auth/genesis.go#L31-L42 ## Next {hide} diff --git a/docs/building-modules/invariants.md b/docs/building-modules/invariants.md index 7904b3dc1646..3614bbc0a4df 100644 --- a/docs/building-modules/invariants.md +++ b/docs/building-modules/invariants.md @@ -14,7 +14,7 @@ An invariant is a property of the application that should always be true. In the An `Invariant` is a function that checks for a particular invariant within a module. Module `Invariant`s must follow the `Invariant` type: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/invariant.go#L9 The `string` return value is the invariant message, which can be used when printing logs, and the `bool` return value is the actual result of the invariant check. @@ -69,17 +69,17 @@ The `InvariantRegistry` is a registry where the `Invariant`s of all the modules At its core, the `InvariantRegistry` is defined in the Cosmos SDK as an interface: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/invariant.go#L14-L17 Typically, this interface is implemented in the `keeper` of a specific module. The most used implementation of an `InvariantRegistry` can be found in the `crisis` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/crisis/keeper/keeper.go#L50-L54 The `InvariantRegistry` is therefore typically instantiated by instantiating the `keeper` of the `crisis` module in the [application's constructor function](../basics/app-anatomy.md#constructor-function). `Invariant`s can be checked manually via [`message`s](./messages-and-queries.md), but most often they are checked automatically at the end of each block. Here is an example from the `crisis` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/crisis/abci.go#L7-L14 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). diff --git a/docs/building-modules/keeper.md b/docs/building-modules/keeper.md index 7216ea35532a..515dc35318fc 100644 --- a/docs/building-modules/keeper.md +++ b/docs/building-modules/keeper.md @@ -34,7 +34,7 @@ type Keeper struct { For example, here is the type definition of the `keeper` from the `staking` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/3bafd8255a502e5a9cee07391cf8261538245dfd/x/staking/keeper/keeper.go#L23-L33 Let us go through the different parameters: @@ -78,7 +78,7 @@ The [module `KVStore`](../core/store.md#kvstore-and-commitkvstore-interfaces) al This is an example from the `auth` module to iterate accounts: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/bf8809ef9840b4f5369887a38d8345e2380a567f/x/auth/keeper/account.go#L70-L83 ## Next {hide} diff --git a/docs/building-modules/messages-and-queries.md b/docs/building-modules/messages-and-queries.md index fece3eb1fa5a..103d17e941e6 100644 --- a/docs/building-modules/messages-and-queries.md +++ b/docs/building-modules/messages-and-queries.md @@ -22,7 +22,7 @@ Starting from v0.40, defining Protobuf `Msg` services is the recommended way to See an example of a `Msg` service definition from `x/bank` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/proto/cosmos/bank/v1beta1/tx.proto#L10-L17 Each `Msg` service method must have exactly one argument, which must implement the `sdk.Msg` interface, and a Protobuf response. The naming convention is to call the RPC argument `Msg` and the RPC response `MsgResponse`. For example: @@ -49,7 +49,7 @@ Amino `LegacyMsg`s can be defined as protobuf messages. The messages definition A `LegacyMsg` is typically accompanied by a standard constructor function, that is called from one of the [module's interface](./module-interfaces.md). `message`s also need to implement the `sdk.Msg` interface: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/4a1b2fba43b1052ca162b3a1e0b6db6db9c26656/types/tx_msg.go#L10-L33 It extends `proto.Message` and contains the following methods: @@ -61,7 +61,7 @@ It extends `proto.Message` and contains the following methods: See an example implementation of a `message` from the `gov` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/x/gov/types/msgs.go#L77-L125 ## Queries @@ -73,7 +73,7 @@ Starting from v0.40, the prefered way to define queries is by using [Protobuf se Here's an example of such a `Query` service definition: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/proto/cosmos/auth/v1beta1/query.proto#L12-L23 As `proto.Message`s, generated `Response` types implement by default `String()` method of [`fmt.Stringer`](https://golang.org/pkg/fmt/#Stringer). @@ -106,9 +106,9 @@ Store queries query directly for store keys. They use `clientCtx.QueryABCI(req a See following examples: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/080fcf1df25ccdf97f3029b6b6f83caaf5a235e4/x/ibc/core/client/query.go#L36-L46 -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/080fcf1df25ccdf97f3029b6b6f83caaf5a235e4/baseapp/abci.go#L722-L749 ## Next {hide} diff --git a/docs/building-modules/module-interfaces.md b/docs/building-modules/module-interfaces.md index f88902d589ac..c4fe187a9758 100644 --- a/docs/building-modules/module-interfaces.md +++ b/docs/building-modules/module-interfaces.md @@ -22,7 +22,7 @@ One of the main interfaces for an application is the [command-line interface](.. Here is an example from the `x/bank` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/bank/client/cli/tx.go#L28-L63 In the example, `NewSendTxCmd()` creates and returns the transaction command for a transaction that wraps and delivers `MsgSend`. `MsgSend` is the message used to send tokens from one account to another. @@ -42,17 +42,17 @@ In general, the getter function does the following: Each module must implement `NewTxCmd()`, which aggregates all of the transaction commands of the module. Here is an example from the `x/bank` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/bank/client/cli/tx.go#L13-L26 Each module must also implement the `GetTxCmd()` method for `AppModuleBasic` that simply returns `NewTxCmd()`. This allows the root command to easily aggregate all of the transaction commands for each module. Here is an example: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/bank/module.go#L75-L78 ### Query Commands [Queries](./messages-and-queries.md#queries) allow users to gather information about the application or network state; they are routed by the application and processed by the module in which they are defined. Query commands typically have their own `query.go` file in the module's `./client/cli` folder. Like transaction commands, they are specified in getter functions. Here is an example of a query command from the `x/auth` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/auth/client/cli/query.go#L75-L105 In the example, `GetAccountCmd()` creates and returns a query command that returns the state of an account based on the provided account address. @@ -72,11 +72,11 @@ In general, the getter function does the following: Each module must implement `GetQueryCmd()`, which aggregates all of the query commands of the module. Here is an example from the `x/auth` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/auth/client/cli/query.go#L25-L42 Each module must also implement the `GetQueryCmd()` method for `AppModuleBasic` that returns the `GetQueryCmd()` function. This allows for the root command to easily aggregate all of the query commands for each module. Here is an example: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/auth/module.go#L80-L83 ### Flags @@ -102,13 +102,13 @@ For more detailed information on creating flags, visit the [Cobra Documentation] As mentioned in [transaction commands](#transaction-commands), there is a set of flags that all transaction commands must add. This is done with the `AddTxFlagsToCmd` method defined in the Cosmos SDK's `./client/flags` package. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/client/flags/flags.go#L94-L120 Since `AddTxFlagsToCmd(cmd *cobra.Command)` includes all of the basic flags required for a transaction command, module developers may choose not to add any of their own (specifying arguments instead may often be more appropriate). Similarly, there is a `AddQueryFlagsToCmd(cmd *cobra.Command)` to add common flags to a module query command. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/client/flags/flags.go#L85-L92 ## gRPC @@ -120,7 +120,7 @@ In order to do that, modules must implement `RegisterGRPCGatewayRoutes(clientCtx Here's an example from the `x/auth` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/auth/module.go#L68-L73 ## gRPC-gateway REST @@ -128,7 +128,7 @@ Applications need to support web services that use HTTP requests (e.g. a web wal Modules that want to expose REST queries should add `google.api.http` annotations to their `rpc` methods, such as in the example below from the `x/auth` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/auth/v1beta1/query.proto#L13-L29 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). diff --git a/docs/building-modules/module-manager.md b/docs/building-modules/module-manager.md index 9851d956f562..eef5d06e6d44 100644 --- a/docs/building-modules/module-manager.md +++ b/docs/building-modules/module-manager.md @@ -29,7 +29,7 @@ are only used for genesis can take advantage of the `Module` patterns without ha The `AppModuleBasic` interface defines the independent methods modules need to implement. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/325be6ff215db457c6fc7668109640cd7fdac461/types/module/module.go#L49-L63 Let us go through the methods: @@ -49,7 +49,7 @@ All the `AppModuleBasic` of an application are managed by the [`BasicManager`](# The `AppModuleGenesis` interface is a simple embedding of the `AppModuleBasic` interface with two added methods. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/325be6ff215db457c6fc7668109640cd7fdac461/types/module/module.go#L152-L158 Let us go through the two added methods: @@ -62,7 +62,7 @@ It does not have its own manager, and exists separately from [`AppModule`](#appm The `AppModule` interface defines the inter-dependent methods that modules need to implement. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/b4cce159bcc6a32ac78245c6866dd87c73f3720d/types/module/module.go#L160-L182 `AppModule`s are managed by the [module manager](#manager). This interface embeds the `AppModuleGenesis` interface so that the manager can access all the independent and genesis inter-dependent methods of the module. This means that a concrete type implementing the `AppModule` interface must either implement all the methods of `AppModuleGenesis` (and by extension `AppModuleBasic`), or include a concrete type that does as parameter. @@ -106,7 +106,7 @@ Module managers are used to manage collections of `AppModuleBasic` and `AppModul The `BasicManager` is a structure that lists all the `AppModuleBasic` of an application: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/325be6ff215db457c6fc7668109640cd7fdac461/types/module/module.go#L65-L66 It implements the following methods: @@ -124,7 +124,7 @@ It implements the following methods: The `Manager` is a structure that holds all the `AppModule` of an application, and defines the order of execution between several key components of these modules: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/325be6ff215db457c6fc7668109640cd7fdac461/types/module/module.go#L223-L231 The module manager is used throughout the application whenever an action on a collection of modules is required. It implements the following methods: @@ -143,7 +143,7 @@ The module manager is used throughout the application whenever an action on a co Here's an example of a concrete integration within an application: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/2323f1ac0e9a69a0da6b43693061036134193464/simapp/app.go#L315-L362 ## Next {hide} diff --git a/docs/building-modules/msg-services.md b/docs/building-modules/msg-services.md index 1c6bffbb7ef6..cb52425ff8fc 100644 --- a/docs/building-modules/msg-services.md +++ b/docs/building-modules/msg-services.md @@ -19,15 +19,15 @@ As further described in [ADR 031](../architecture/adr-031-msg-service.md), this Protobuf generates a `MsgServer` interface based on a definition of `Msg` service. It is the role of the module developer to implement this interface, by implementing the state transition logic that should happen upon receival of each `sdk.Msg`. As an example, here is the generated `MsgServer` interface for `x/bank`, which exposes two `sdk.Msg`s: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/x/bank/types/tx.pb.go#L285-L291 When possible, the existing module's [`Keeper`](keeper.md) should implement `MsgServer`, otherwise a `msgServer` struct that embeds the `Keeper` can be created, typically in `./keeper/msg_server.go`: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/x/bank/keeper/msg_server.go#L14-L16 `msgServer` methods can retrieve the `sdk.Context` from the `context.Context` parameter method using the `sdk.UnwrapSDKContext`: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/x/bank/keeper/msg_server.go#L27-L28 `sdk.Msg` processing usually follows these 3 steps: @@ -77,11 +77,11 @@ These events are relayed back to the underlying consensus engine and can be used The invoked `msgServer` method returns a `proto.Message` response and an `error`. These return values are then wrapped into an `*sdk.Result` or an `error` using `sdk.WrapServiceResult(ctx sdk.Context, res proto.Message, err error)`: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc2/baseapp/msg_service_router.go#L104-L104 This method takes care of marshaling the `res` parameter to protobuf and attaching any events on the `ctx.EventManager()` to the `sdk.Result`. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/proto/cosmos/base/abci/v1beta1/abci.proto#L81-L95 This diagram shows a typical structure of a Protobuf `Msg` service, and how the message propagates through the module. @@ -95,7 +95,7 @@ The `handler` type defined in the Cosmos SDK will be deprecated in favor of [`Ms Here is the typical structure of a `handler` function: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc2/types/handler.go#L4-L4 Let us break it down: @@ -107,13 +107,13 @@ Module `handler`s are typically implemented in a `./handler.go` file inside the [application's `router`](../core/baseapp.md#message-routing) via the `Route()` method. Typically, the manager's `Route()` method simply constructs a Route that calls a `NewHandler()` method defined in `handler.go`. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/228728cce2af8d494c8b4e996d011492139b04ab/x/gov/module.go#L143-L146 ### Implementation `NewHandler` function dispatches a `LegacyMsg` to appropriate handler function, usually by using a switch statement: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/x/bank/handler.go#L13-L29 First, `NewHandler` function sets a new `EventManager` to the context to isolate events per `msg`. Then, a simple switch calls the appropriate `handler` based on the `LegacyMsg` type. @@ -127,7 +127,7 @@ New [telemetry metrics](../core/telemetry.md) can be created from `msgServer` me This is an example from the `x/auth/vesting` module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc1/x/auth/vesting/msg_server.go#L73-L85 ## Next {hide} diff --git a/docs/building-modules/query-services.md b/docs/building-modules/query-services.md index bf5ae73b92f1..bb994f08e435 100644 --- a/docs/building-modules/query-services.md +++ b/docs/building-modules/query-services.md @@ -15,7 +15,7 @@ A Protobuf Query service processes [`queries`](./messages-and-queries.md#queries The `querier` type defined in the Cosmos SDK will be deprecated in favor of [gRPC Services](#grpc-service). It specifies the typical structure of a `querier` function: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/9a183ffbcc0163c8deb71c7fd5f8089a83e58f05/types/queryable.go#L9 Let us break it down: @@ -43,7 +43,7 @@ from the store. Therefore, the Cosmos SDK provides a function `sdk.UnwrapSDKCont Here's an example implementation for the bank module: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/d55c1a26657a0af937fa2273b38dcfa1bb3cff9f/x/bank/keeper/grpc_query.go ### Legacy Queriers diff --git a/docs/building-modules/simulator.md b/docs/building-modules/simulator.md index 7921294c6246..ab5801160dbb 100644 --- a/docs/building-modules/simulator.md +++ b/docs/building-modules/simulator.md @@ -62,13 +62,13 @@ Operations on the simulation are simulated using the full [transaction cycle](.. Shown below is how weights are set: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/staking/simulation/operations.go#L18-L68 As you can see, the weights are predefined in this case. Options exist to override this behavior with different weights. One option is to use `*rand.Rand` to define a random weight for the operation, or you can inject your own predefined weights. Here is how one can override the above package `simappparams`. -+++ ++++ https://github.com/cosmos/gaia/blob/master/sims.mk#L9-L22 For the last test a tool called runsim is used, this is used to parallelize go test instances, provide info to Github and slack integrations to provide information to your team on how the simulations are running. @@ -82,7 +82,7 @@ them to be used on the parameters. Now that all the required functions are defined, we need to integrate them into the module pattern within the `module.go`: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.0/x/distribution/module.go ## App Simulator manager diff --git a/docs/building-modules/upgrade.md b/docs/building-modules/upgrade.md index 720643f800af..fc57ec46a1e5 100644 --- a/docs/building-modules/upgrade.md +++ b/docs/building-modules/upgrade.md @@ -41,7 +41,7 @@ func (am AppModule) RegisterServices(cfg module.Configurator) { Since these migrations are functions that need access to a Keeper's store, use a wrapper around the keepers called `Migrator` as shown in this example: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/6ac8898fec9bd7ea2c1e5c79e0ed0c3f827beb55/x/bank/keeper/migrations.go#L8-L21 ## Writing Migration Scripts diff --git a/docs/core/baseapp.md b/docs/core/baseapp.md index 94fbd1424ed6..7d2850b71f99 100644 --- a/docs/core/baseapp.md +++ b/docs/core/baseapp.md @@ -45,7 +45,7 @@ management logic. The `BaseApp` type holds many important parameters for any Cosmos SDK based application. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/baseapp/baseapp.go#L46-L131 Let us go through the most important components. @@ -263,7 +263,7 @@ The response contains: * `Info (string):` Additional information. May be non-deterministic. * `GasWanted (int64)`: Amount of gas requested for transaction. It is provided by users when they generate the transaction. * `GasUsed (int64)`: Amount of gas consumed by transaction. During `CheckTx`, this value is computed by multiplying the standard cost of a transaction byte by the size of the raw transaction. Next is an example: - +++ + +++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/auth/ante/basic.go#L104-L105 * `Events ([]cmn.KVPair)`: Key-Value tags for filtering and indexing transactions (eg. by account). See [`event`s](./events.md) for more. * `Codespace (string)`: Namespace for the Code. @@ -289,7 +289,7 @@ Before the first transaction of a given block is processed, a [volatile state](# During the additional fifth step outlined in (2), each read/write to the store increases the value of `GasConsumed`. You can find the default cost of each operation: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/store/types/gas.go#L164-L175 At any point, if `GasConsumed > GasWanted`, the function returns with `Code != 0` and `DeliverTx` fails. @@ -316,7 +316,7 @@ After that, `RunTx()` calls `ValidateBasic()` on each `sdk.Msg`in the `Tx`, whic Then, the [`anteHandler`](#antehandler) of the application is run (if it exists). In preparation of this step, both the `checkState`/`deliverState`'s `context` and `context`'s `CacheMultiStore` are branched using the `cacheTxContext()` function. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/baseapp/baseapp.go#L623-L630 This allows `RunTx` not to commit the changes made to the state during the execution of `anteHandler` if it ends up failing. It also prevents the module implementing the `anteHandler` from writing to state, which is an important part of the [object-capabilities](./ocap.md) of the Cosmos SDK. @@ -326,7 +326,7 @@ Finally, the [`RunMsgs()`](#runmsgs) function is called to process the `sdk.Msg` The `AnteHandler` is a special handler that implements the `AnteHandler` interface and is used to authenticate the transaction before the transaction's internal messages are processed. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/handler.go#L6-L8 The `AnteHandler` is theoretically optional, but still a very important component of public blockchain networks. It serves 3 primary purposes: @@ -361,7 +361,7 @@ Finally, the `InitChain(req abci.RequestInitChain)` method of `BaseApp` calls th The [`BeginBlock` ABCI message](#https://tendermint.com/docs/app-dev/abci-spec.html#beginblock) is sent from the underlying Tendermint engine when a block proposal created by the correct proposer is received, before [`DeliverTx`](#delivertx) is run for each transaction in the block. It allows developers to have logic be executed at the beginning of each block. In the Cosmos SDK, the `BeginBlock(req abci.RequestBeginBlock)` method does the following: * Initialize [`deliverState`](#volatile-states) with the latest header using the `req abci.RequestBeginBlock` passed as parameter via the `setDeliverState` function. - +++ + +++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/baseapp/baseapp.go#L387-L397 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. diff --git a/docs/core/cli.md b/docs/core/cli.md index 1c9c0c253880..cc0765894079 100644 --- a/docs/core/cli.md +++ b/docs/core/cli.md @@ -40,7 +40,7 @@ The `main.go` file needs to have a `main()` function that creates a root command The `main()` function finally creates an executor and [execute](https://godoc.org/github.com/spf13/cobra#Command.Execute) the root command. See an example of `main()` function from the `simapp` application: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/main.go#L12-L24 The rest of the document will detail what needs to be implemented for each step and include smaller portions of code from the `simapp` CLI files. @@ -60,17 +60,17 @@ The root command (called `rootCmd`) is what the user first types into the comman Next is an example `rootCmd` function from the `simapp` application. It instantiates the root command, adds a [_persistent_ flag](#flags) and `PreRun` function to be run before every execution, and adds all of the necessary subcommands. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/simapp/simd/cmd/root.go#L37-L150 `rootCmd` has a function called `initAppConfig()` which is useful for setting the application's custom configs. By default app uses Tendermint app config template from Cosmos SDK, which can be over-written via `initAppConfig()`. Here's an example code to override default `app.toml` template. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/simapp/simd/cmd/root.go#L84-L117 The `initAppConfig()` also allows overriding the default Cosmos SDK's [server config](https://github.com/cosmos/cosmos-sdk/blob/4eea4cafd3b8b1c2cd493886db524500c9dd745c/server/config/config.go#L199). One example is the `min-gas-prices` config, which defines the minimum gas prices a validator is willing to accept for processing a transaction. By default, the Cosmos SDK sets this parameter to `""` (empty string), which forces all validators to tweak their own `app.toml` and set a non-empty value, or else the node will halt on startup. This might not be the best UX for validators, so the chain developer can set a default `app.toml` value for validators inside this `initAppConfig()` function. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/aa9b055ddb46aacd4737335a92d0b8a82d577341/simapp/simd/cmd/root.go#L101-L116 The root-level `status` and `keys` subcommands are common across most applications and do not interact with application state. The bulk of an application's functionality - what users can actually _do_ with it - is enabled by its `tx` and `query` commands. @@ -78,7 +78,7 @@ The root-level `status` and `keys` subcommands are common across most applicatio [Transactions](./transactions.md) are objects wrapping [`Msg`s](../building-modules/messages-and-queries.md#messages) that trigger state changes. To enable the creation of transactions using the CLI interface, a function `txCmd` is generally added to the `rootCmd`: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L86-L92 This `txCmd` function adds all the transaction available to end-users for the application. This typically includes: @@ -88,13 +88,13 @@ This `txCmd` function adds all the transaction available to end-users for the ap Here is an example of a `txCmd` aggregating these subcommands from the `simapp` application: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L123-L149 ### Query Commands [**Queries**](../building-modules/messages-and-queries.md#queries) are objects that allow users to retrieve information about the application's state. To enable the creation of transactions using the CLI interface, a function `txCmd` is generally added to the `rootCmd`: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L86-L92 This `queryCmd` function adds all the queries available to end-users for the application. This typically includes: @@ -106,7 +106,7 @@ This `queryCmd` function adds all the queries available to end-users for the app Here is an example of a `queryCmd` aggregating subcommands from the `simapp` application: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L99-L121 ## Flags @@ -116,7 +116,7 @@ A _persistent_ flag (as opposed to a _local_ flag) added to a command transcends Flags are added to commands directly (generally in the [module's CLI file](../building-modules/module-interfaces.md#flags) where module commands are defined) and no flag except for the `rootCmd` persistent flags has to be added at application level. It is common to add a _persistent_ flag for `--chain-id`, the unique identifier of the blockchain the application pertains to, to the root command. Adding this flag can be done in the `main()` function. Adding this flag makes sense as the chain ID should not be changing across commands in this application CLI. Here is an example from the `simapp` application: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L118-L119 ## Environment variables @@ -145,7 +145,7 @@ It is vital that the root command of an application uses `PersistentPreRun()` co Here is an example of an `PersistentPreRun()` function from `simapp``: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/simapp/simd/cmd/root.go#L54-L60 The `SetCmdClientContextHandler` call reads persistent flags via `ReadPersistentCommandFlags` which creates a `client.Context` and sets that on the root command's `Context`. diff --git a/docs/core/context.md b/docs/core/context.md index 6fd2977af5e8..3a0efa4353de 100644 --- a/docs/core/context.md +++ b/docs/core/context.md @@ -15,7 +15,7 @@ The `context` is a data structure intended to be passed from function to functio The Cosmos SDK `Context` is a custom data structure that contains Go's stdlib [`context`](https://golang.org/pkg/context) as its base, and has many additional types within its definition that are specific to the Cosmos SDK. The `Context` is integral to transaction processing in that it allows modules to easily access their respective [store](./store.md#base-layer-kvstores) in the [`multistore`](./store.md#multistore) and retrieve transactional context such as the block header and gas meter. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/context.go#L16-L39 * **Context:** The base type is a Go [Context](https://golang.org/pkg/context), which is explained further in the [Go Context Package](#go-context-package) section below. * **Multistore:** Every application's `BaseApp` contains a [`CommitMultiStore`](./store.md#multistore) which is provided when a `Context` is created. Calling the `KVStore()` and `TransientStore()` methods allows modules to fetch their respective [`KVStore`](./store.md#base-layer-kvstores) using their unique `StoreKey`. diff --git a/docs/core/encoding.md b/docs/core/encoding.md index 106117630120..30f472c01627 100644 --- a/docs/core/encoding.md +++ b/docs/core/encoding.md @@ -91,13 +91,13 @@ the consensus engine accepts only transactions in the form of raw bytes. * The `TxEncoder` object performs the encoding. * The `TxDecoder` object performs the decoding. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/types/tx_msg.go#L83-L87 A standard implementation of both these objects can be found in the [`auth` module](../../x/auth/spec/README.md): -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/x/auth/tx/decoder.go -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/x/auth/tx/encoder.go See [ADR-020](../architecture/adr-020-protobuf-transaction-encoding.md) for details of how a transaction is encoded. @@ -116,7 +116,7 @@ message Profile { In this `Profile` example, we hardcoded `account` as a `BaseAccount`. However, there are several other types of [user accounts related to vesting](../../x/auth/spec/05_vesting.md), such as `BaseVestingAccount` or `ContinuousVestingAccount`. All of these accounts are different, but they all implement the `AccountI` interface. How would you create a `Profile` that allows all these types of accounts with an `account` field that accepts an `AccountI` interface? -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/auth/types/account.go#L307-L330 In [ADR-019](../architecture/adr-019-protobuf-state-encoding.md), it has been decided to use [`Any`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto)s to encode interfaces in protobuf. An `Any` contains an arbitrary serialized message as bytes, along with a URL that acts as a globally unique identifier for and resolves to that message's type. This strategy allows us to pack arbitrary Go types inside protobuf messages. Our new `Profile` then looks like: @@ -202,7 +202,7 @@ The above `Profile` example is a fictive example used for educational purposes. A real-life example of encoding the pubkey as `Any` inside the Validator struct in x/staking is shown in the following example: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/x/staking/types/validator.go#L40-L61 ## FAQ @@ -246,7 +246,7 @@ The Cosmos SDK `codec.Codec` interface provides support methods `MarshalInterfac Module should register interfaces using `InterfaceRegistry` which provides a mechanism for registering interfaces: `RegisterInterface(protoName string, iface interface{})` and implementations: `RegisterImplementations(iface interface{}, impls ...proto.Message)` that can be safely unpacked from Any, similarly to type registration with Amino: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc4/codec/types/interface_registry.go#L25-L66 In addition, an `UnpackInterfaces` phase should be introduced to deserialization to unpack interfaces before they're needed. Protobuf types that contain a protobuf `Any` either directly or via one of their members should implement the `UnpackInterfacesMessage` interface: diff --git a/docs/core/events.md b/docs/core/events.md index 3769cf9955b0..616f9c6541e3 100644 --- a/docs/core/events.md +++ b/docs/core/events.md @@ -16,7 +16,7 @@ order: 9 Events are implemented in the Cosmos SDK as an alias of the ABCI `Event` type and take the form of: `{eventType}.{attributeKey}={attributeValue}`. -+++ ++++ https://github.com/tendermint/tendermint/blob/v0.34.8/proto/tendermint/abci/types.proto#L304-L313 An Event contains: @@ -57,13 +57,13 @@ In Cosmos SDK applications, Events are managed by an abstraction called the `Eve Internally, the `EventManager` tracks a list of Events for the entire execution flow of a transaction or `BeginBlock`/`EndBlock`. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/events.go#L17-L25 The `EventManager` comes with a set of useful methods to manage Events. The method that is used most by module and application developers is `EmitEvent` that tracks an Event in the `EventManager`. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/events.go#L33-L37 Module developers should handle Event emission via the `EventManager#EmitEvent` in each message `Handler` and in each `BeginBlock`/`EndBlock` handler. The `EventManager` is accessed via diff --git a/docs/core/grpc_rest.md b/docs/core/grpc_rest.md index 5fb4c78ef5ed..c52327be18b7 100644 --- a/docs/core/grpc_rest.md +++ b/docs/core/grpc_rest.md @@ -36,7 +36,7 @@ Cosmos SDK v0.40 introduced Protobuf as the main [encoding](./encoding) library, Each module exposes a [Protobuf `Query` service](../building-modules/messages-and-queries.md#queries) that defines state queries. The `Query` services and a transaction service used to broadcast transactions are hooked up to the gRPC server via the following function inside the application: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-rc0/server/types/app.go#L39-L41 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. @@ -69,7 +69,7 @@ If, for various reasons, you cannot use gRPC (for example, you are building a we [gRPC-gateway](https://grpc-ecosystem.github.io/grpc-gateway/) is a tool to expose gRPC endpoints as REST endpoints. For each gRPC endpoint defined in a Protobuf `Query` service, the Cosmos SDK offers a REST equivalent. For instance, querying a balance could be done via the `/cosmos.bank.v1beta1.QueryAllBalances` gRPC endpoint, or alternatively via the gRPC-gateway `"/cosmos/bank/v1beta1/balances/{address}"` REST endpoint: both will return the same result. For each RPC method defined in a Protobuf `Query` service, the corresponding REST endpoint is defined as an option: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.41.0/proto/cosmos/bank/v1beta1/query.proto#L19-L22 For application developers, gRPC-gateway REST routes needs to be wired up to the REST server, this is done by calling the `RegisterGRPCGatewayRoutes` function on the ModuleManager. diff --git a/docs/core/node.md b/docs/core/node.md index b7790eac0b6e..3c61291cf3e0 100644 --- a/docs/core/node.md +++ b/docs/core/node.md @@ -18,15 +18,15 @@ In general, developers will implement the `main.go` function with the following * First, an [`appCodec`](./encoding.md) is instantiated for the application. * Then, the `config` is retrieved and config parameters are set. This mainly involves setting the Bech32 prefixes for [addresses](../basics/accounts.md#addresses). - +++ + +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/config.go#L13-L24 * Using [cobra](https://github.com/spf13/cobra), the root command of the full-node client is created. After that, all the custom commands of the application are added using the `AddCommand()` method of `rootCmd`. * Add default server commands to `rootCmd` using the `server.AddCommands()` method. These commands are separated from the ones added above since they are standard and defined at Cosmos SDK level. They should be shared by all Cosmos SDK-based applications. They include the most important command: the [`start` command](#start-command). * Prepare and execute the `executor`. - +++ + +++ https://github.com/tendermint/tendermint/blob/v0.34.0-rc6/libs/cli/setup.go#L74-L78 See an example of `main` function from the `simapp` application, the Cosmos SDK's application for demo purposes: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/simd/main.go ## `start` command @@ -46,24 +46,24 @@ The flow of the `start` command is pretty straightforward. First, it retrieves t With the `db`, the `start` command creates a new instance of the application using an `appCreator` function: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/start.go#L227-L228 Note that an `appCreator` is a function that fulfills the `AppCreator` signature: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/types/app.go#L48-L50 In practice, the [constructor of the application](../basics/app-anatomy.md#constructor-function) is passed as the `appCreator`. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/simapp/simd/cmd/root.go#L170-L215 Then, the instance of `app` is used to instanciate a new Tendermint node: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/start.go#L235-L244 The Tendermint node can be created with `app` because the latter satisfies the [`abci.Application` interface](https://github.com/tendermint/tendermint/blob/v0.34.0/abci/types/application.go#L7-L32) (given that `app` extends [`baseapp`](./baseapp.md)). As part of the `NewNode` method, Tendermint makes sure that the height of the application (i.e. number of blocks since genesis) is equal to the height of the Tendermint node. The difference between these two heights should always be negative or null. If it is strictly negative, `NewNode` will replay blocks until the height of the application reaches the height of the Tendermint node. Finally, if the height of the application is `0`, the Tendermint node will call [`InitChain`](./baseapp.md#initchain) on the application to initialize the state from the genesis file. Once the Tendermint node is instanciated and in sync with the application, the node can be started: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/server/start.go#L250-L252 Upon starting, the node will bootstrap its RPC and P2P server and start dialing peers. During handshake with its peers, if the node realizes they are ahead, it will query all the blocks sequentially in order to catch up. Then, it will wait for new block proposals and block signatures from validators in order to make progress. diff --git a/docs/core/ocap.md b/docs/core/ocap.md index 0c21095f3bb3..a365fd106ec2 100644 --- a/docs/core/ocap.md +++ b/docs/core/ocap.md @@ -68,7 +68,7 @@ sumValue := externalModule.ComputeSumValue(*account) In the Cosmos SDK, you can see the application of this principle in the gaia app. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.41.4/simapp/app.go#L249-L273 The following diagram shows the current dependencies between keepers. diff --git a/docs/core/store.md b/docs/core/store.md index 95c83822d6b1..506c38f558ba 100644 --- a/docs/core/store.md +++ b/docs/core/store.md @@ -58,11 +58,11 @@ The Cosmos SDK comes with a large set of stores to persist the state of applicat At its very core, a Cosmos SDK `store` is an object that holds a `CacheWrapper` and has a `GetStoreType()` method: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L15-L18 The `GetStoreType` is a simple method that returns the type of store, whereas a `CacheWrapper` is a simple interface that implements store read caching and write branching through `Write` method: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L240-L264 Branching and cache is used ubiquitously in the Cosmos SDK and required to be implemented on every store type. A storage branch creates an isolated, ephemeral branch of a store that can be passed around and updated without affecting the main underlying store. This is used to trigger temporary state-transitions that may be reverted later should an error occur. Read more about it in [context](./context.md#Store-branching) @@ -70,11 +70,11 @@ Branching and cache is used ubiquitously in the Cosmos SDK and required to be im A commit store is a store that has the ability to commit changes made to the underlying tree or db. The Cosmos SDK differentiates simple stores from commit stores by extending the basic store interfaces with a `Committer`: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L29-L33 The `Committer` is an interface that defines methods to persist changes to disk: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L20-L27 The `CommitID` is a deterministic commit of the state tree. Its hash is returned to the underlying consensus engine and stored in the block header. Note that commit store interfaces exist for various purposes, one of which is to make sure not every object can commit the store. As part of the [object-capabilities model](./ocap.md) of the Cosmos SDK, only `baseapp` should have the ability to commit stores. For example, this is the reason why the `ctx.KVStore()` method by which modules typically access stores returns a `KVStore` and not a `CommitKVStore`. @@ -86,7 +86,7 @@ The Cosmos SDK comes with many types of stores, the most used being [`CommitMult Each Cosmos SDK application holds a multistore at its root to persist its state. The multistore is a store of `KVStores` that follows the `Multistore` interface: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L104-L133 If tracing is enabled, then branching the multistore will firstly wrap all the underlying `KVStore` in [`TraceKv.Store`](#tracekv-store). @@ -94,11 +94,11 @@ If tracing is enabled, then branching the multistore will firstly wrap all the u The main type of `Multistore` used in the Cosmos SDK is `CommitMultiStore`, which is an extension of the `Multistore` interface: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L141-L184 As for concrete implementation, the [`rootMulti.Store`] is the go-to implementation of the `CommitMultiStore` interface. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/rootmulti/store.go#L43-L61 The `rootMulti.Store` is a base-layer multistore built around a `db` on top of which multiple `KVStores` can be mounted, and is the default multistore store used in [`baseapp`](./baseapp.md). @@ -106,7 +106,7 @@ The `rootMulti.Store` is a base-layer multistore built around a `db` on top of w Whenever the `rootMulti.Store` needs to be branched, a [`cachemulti.Store`](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/store/cachemulti/store.go) is used. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/cachemulti/store.go#L17-L28 `cachemulti.Store` branches all substores (creates a virtual store for each substore) in its constructor and hold them in `Store.stores`. Moreover caches all read queries. `Store.GetKVStore()` returns the store from `Store.stores`, and `Store.Write()` recursively calls `CacheWrap.Write()` on all the substores. @@ -120,17 +120,17 @@ Individual `KVStore`s are used by modules to manage a subset of the global state `CommitKVStore`s are declared by proxy of their respective `key` and mounted on the application's [multistore](#multistore) in the [main application file](../basics/app-anatomy.md#core-application-file). In the same file, the `key` is also passed to the module's `keeper` that is responsible for managing the store. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/store.go#L189-L219 Apart from the traditional `Get` and `Set` methods, a `KVStore` must provide an `Iterator(start, end)` method which returns an `Iterator` object. It is used to iterate over a range of keys, typically keys that share a common prefix. Below is an example from the bank's module keeper, used to iterate over all account balances: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/x/bank/keeper/view.go#L115-L134 ### `IAVL` Store The default implementation of `KVStore` and `CommitKVStore` used in `baseapp` is the `iavl.Store`. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/iavl/store.go#L37-L40 `iavl` stores are based around an [IAVL Tree](https://github.com/tendermint/iavl), a self-balancing binary tree which guarantees that: @@ -144,7 +144,7 @@ The documentation on the IAVL Tree is located [here](https://github.com/cosmos/i `dbadapter.Store` is a adapter for `dbm.DB` making it fulfilling the `KVStore` interface. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/dbadapter/store.go#L13-L16 `dbadapter.Store` embeds `dbm.DB`, meaning most of the `KVStore` interface functions are implemented. The other functions (mostly miscellaneous) are manually implemented. This store is primarily used within [Transient Stores](#transient-stores) @@ -152,17 +152,17 @@ The documentation on the IAVL Tree is located [here](https://github.com/cosmos/i `Transient.Store` is a base-layer `KVStore` which is automatically discarded at the end of the block. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/transient/store.go#L13-L16 `Transient.Store` is a `dbadapter.Store` with a `dbm.NewMemDB()`. All `KVStore` methods are reused. When `Store.Commit()` is called, a new `dbadapter.Store` is assigned, discarding previous reference and making it garbage collected. This type of store is useful to persist information that is only relevant per-block. One example would be to store parameter changes (i.e. a bool set to `true` if a parameter changed in a block). -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/x/params/types/subspace.go#L20-L30 Transient stores are typically accessed via the [`context`](./context.md) via the `TransientStore()` method: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/types/context.go#L232-L235 ## KVStore Wrappers @@ -170,7 +170,7 @@ Transient stores are typically accessed via the [`context`](./context.md) via th `cachekv.Store` is a wrapper `KVStore` which provides buffered writing / cached reading functionalities over the underlying `KVStore`. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/cachekv/store.go#L27-L34 This is the type used whenever an IAVL Store needs to be branched to create an isolated store (typically when we need to mutate a state that might be reverted later). @@ -190,25 +190,25 @@ This is the type used whenever an IAVL Store needs to be branched to create an i Cosmos SDK applications use [`gas`](../basics/gas-fees.md) to track resources usage and prevent spam. [`GasKv.Store`](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/gaskv/store.go) is a `KVStore` wrapper that enables automatic gas consumption each time a read or write to the store is made. It is the solution of choice to track storage usage in Cosmos SDK applications. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/gaskv/store.go#L13-L19 When methods of the parent `KVStore` are called, `GasKv.Store` automatically consumes appropriate amount of gas depending on the `Store.gasConfig`: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/gas.go#L153-L162 By default, all `KVStores` are wrapped in `GasKv.Stores` when retrieved. This is done in the `KVStore()` method of the [`context`](./context.md): -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/types/context.go#L227-L230 In this case, the default gas configuration is used: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/types/gas.go#L164-L175 ### `TraceKv` Store `tracekv.Store` is a wrapper `KVStore` which provides operation tracing functionalities over the underlying `KVStore`. It is applied automatically by the Cosmos SDK on all `KVStore` if tracing is enabled on the parent `MultiStore`. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/tracekv/store.go#L20-L43 When each `KVStore` methods are called, `tracekv.Store` automatically logs `traceOperation` to the `Store.writer`. `traceOperation.Metadata` is filled with `Store.context` when it is not nil. `TraceContext` is a `map[string]interface{}`. @@ -216,7 +216,7 @@ When each `KVStore` methods are called, `tracekv.Store` automatically logs `trac `prefix.Store` is a wrapper `KVStore` which provides automatic key-prefixing functionalities over the underlying `KVStore`. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc6/store/prefix/store.go#L15-L21 When `Store.{Get, Set}()` is called, the store forwards the call to its parent, with the key prefixed with the `Store.prefix`. @@ -228,7 +228,7 @@ When `Store.Iterator()` is called, it does not simply prefix the `Store.prefix`, It is applied automatically by the Cosmos SDK on any `KVStore` whose `StoreKey` is specified during state streaming configuration. Additional information about state streaming configuration can be found in the [store/streaming/README.md](../../store/streaming/README.md). -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.44.1/store/listenkv/store.go#L11-L18 When `KVStore.Set` or `KVStore.Delete` methods are called, `listenkv.Store` automatically writes the operations to the set of `Store.listeners`. diff --git a/docs/core/transactions.md b/docs/core/transactions.md index 034f1de24da3..ca146e81d706 100644 --- a/docs/core/transactions.md +++ b/docs/core/transactions.md @@ -20,7 +20,7 @@ When users want to interact with an application and make state changes (e.g. sen Transaction objects are Cosmos SDK types that implement the `Tx` interface -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/types/tx_msg.go#L49-L57 It contains the following methods: @@ -37,11 +37,11 @@ Every message in a transaction must be signed by the addresses specified by its The most used implementation of the `Tx` interface is the Protobuf `Tx` message, which is used in `SIGN_MODE_DIRECT`: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/tx.proto#L12-L25 Because Protobuf serialization is not deterministic, the Cosmos SDK uses an additional `TxRaw` type to denote the pinned bytes over which a transaction is signed. Any user can generate a valid `body` and `auth_info` for a transaction, and serialize these two messages using Protobuf. `TxRaw` then pins the user's exact binary representation of `body` and `auth_info`, called respectively `body_bytes` and `auth_info_bytes`. The document that is signed by all signers of the transaction is `SignDoc` (deterministically serialized using [ADR-027](../architecture/adr-027-deterministic-protobuf-serialization.md)): -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/tx.proto#L47-L64 Once signed by all signers, the `body_bytes`, `auth_info_bytes` and `signatures` are gathered into `TxRaw`, whose serialized bytes are broadcasted over the network. @@ -49,11 +49,11 @@ Once signed by all signers, the `body_bytes`, `auth_info_bytes` and `signatures` The legacy implemention of the `Tx` interface is the `StdTx` struct from `x/auth`: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/x/auth/legacy/legacytx/stdtx.go#L120-L130 The document signed by all signers is `StdSignDoc`: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/x/auth/legacy/legacytx/stdsign.go#L20-L33 which is encoded into bytes using Amino JSON. Once all signatures are gathered into `StdTx`, `StdTx` is serialized using Amino JSON, and these bytes are broadcasted over the network. @@ -90,7 +90,7 @@ While messages contain the information for state transition logic, a transaction The `TxBuilder` interface contains data closely related with the generation of transactions, which an end-user can freely set to generate the desired transaction: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/client/tx_config.go#L32-L45 * `Msg`s, the array of [messages](#messages) included in the transaction. * `GasLimit`, option chosen by the users for how to calculate how much gas they will need to pay. @@ -106,7 +106,7 @@ As there are currently two sign modes for signing transactions, there are also t However, the two implementation of `TxBuilder` should be hidden away from end-users, as they should prefer using the overarching `TxConfig` interface: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/client/tx_config.go#L21-L30 `TxConfig` is an app-wide configuration for managing transactions. Most importantly, it holds the information about whether to sign each transaction with `SIGN_MODE_DIRECT` or `SIGN_MODE_LEGACY_AMINO_JSON`. By calling `txBuilder := txConfig.NewTxBuilder()`, a new `TxBuilder` will be created with the appropriate sign mode. @@ -138,7 +138,7 @@ simd tx send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake [gRPC](https://grpc.io) is introduced in Cosmos SDK 0.40 as the main component for the Cosmos SDK's RPC layer. The principal usage of gRPC is in the context of modules' [`Query` services](../building-modules). However, the Cosmos SDK also exposes a few other module-agnostic gRPC services, one of them being the `Tx` service: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc3/proto/cosmos/tx/v1beta1/service.proto 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. diff --git a/docs/intro/sdk-design.md b/docs/intro/sdk-design.md index ba923a008380..afcbade1833d 100644 --- a/docs/intro/sdk-design.md +++ b/docs/intro/sdk-design.md @@ -17,7 +17,7 @@ Here is a simplified view of how transactions are handled by an application buil `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). See an example of this from the Cosmos SDK application tutorial: -+++ ++++ https://github.com/cosmos/sdk-tutorials/blob/c6754a1e313eb1ed973c5c91dcc606f2fd288811/app.go#L72-L92 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). diff --git a/proto/README.md b/proto/README.md index d3ffe874b02d..ff09f36424ce 100644 --- a/proto/README.md +++ b/proto/README.md @@ -6,4 +6,4 @@ a maintainer by running `buf push` in this folder. User facing documentation should not be placed here but instead goes in `buf.md` and in each protobuf package following the guidelines in -. +https://docs.buf.build/bsr/documentation. diff --git a/scripts/README.md b/scripts/README.md index d6f64c78df95..6c0dd52a99a9 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -24,4 +24,4 @@ export GENTXS_DIR=~/go/src/github.com/cosmos/mainnet/$CHAIN_ID/gentxs Though this script is handy for verifying the gentxs locally, it is advised to use Github Action to validate gentxs. An example can be found here: - +https://github.com/regen-network/mainnet/blob/0bcd387671b9574e893289e39c08a1643cac7d62/.github/workflows/validate-gentx.yml diff --git a/store/README.md b/store/README.md index 49b2e5e804e2..3b1c81a0595a 100644 --- a/store/README.md +++ b/store/README.md @@ -56,7 +56,7 @@ type Store struct { 2. Iteration efficiently returns the sorted elements within the range 3. Each tree version is immutable and can be retrieved even after a commit(depending on the pruning settings) -Specification and implementation of IAVL tree can be found in . +Specification and implementation of IAVL tree can be found in https://github.com/tendermint/iavl. ## GasKV diff --git a/x/auth/spec/05_vesting.md b/x/auth/spec/05_vesting.md index 06e153157628..ec3b3a76086a 100644 --- a/x/auth/spec/05_vesting.md +++ b/x/auth/spec/05_vesting.md @@ -100,19 +100,19 @@ type VestingAccount interface { ### BaseVestingAccount -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L10-L33 ### ContinuousVestingAccount -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L35-L43 ### DelayedVestingAccount -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L45-L53 ### Period -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L56-L62 ```go // Stores all vesting periods passed as part of a PeriodicVestingAccount @@ -122,7 +122,7 @@ type Periods []Period ### PeriodicVestingAccount -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L64-L73 In order to facilitate less ad-hoc type checking and assertions and to support flexibility in account balance usage, the existing `x/bank` `ViewKeeper` interface @@ -142,7 +142,7 @@ type ViewKeeper interface { ### PermanentLockedAccount -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/vesting/v1beta1/vesting.proto#L78-L83 ## Vesting Account Specification diff --git a/x/authz/spec/01_concepts.md b/x/authz/spec/01_concepts.md index 7776ae237069..cfa46a09f0e2 100644 --- a/x/authz/spec/01_concepts.md +++ b/x/authz/spec/01_concepts.md @@ -14,7 +14,7 @@ Authorization is an interface that must be implemented by a concrete authorizati **Note:** The authz module is different from the [auth (authentication)](../modules/auth/) module that is responsible for specifying the base transaction and account types. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/authz/authorizations.go#L11-L25 ## Built-in Authorizations @@ -24,9 +24,9 @@ The Cosmos SDK `x/authz` module comes with following authorization types: `GenericAuthorization` implements the `Authorization` interface that gives unrestricted permission to execute the provided Msg on behalf of granter's account. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/authz.proto#L14-L19 -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/authz/generic_authorization.go#L18-L31 * `msg` stores Msg type URL. @@ -34,9 +34,9 @@ The Cosmos SDK `x/authz` module comes with following authorization types: `SendAuthorization` implements the `Authorization` interface for the `cosmos.bank.v1beta1.MsgSend` Msg. It takes a `SpendLimit` that specifies the maximum amount of tokens the grantee can spend. The `SpendLimit` is updated as the tokens are spent. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/bank/v1beta1/authz.proto#L10-L19 -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/bank/types/send_authorization.go#L25-L40 * `spend_limit` keeps track of how many coins are left in the authorization. @@ -44,9 +44,9 @@ The Cosmos SDK `x/authz` module comes with following authorization types: `StakeAuthorization` implements the `Authorization` interface for messages in the [staking module](https://docs.cosmos.network/v0.44/modules/staking/). It takes an `AuthorizationType` to specify whether you want to authorise delegating, undelegating or redelegating (i.e. these have to be authorised seperately). It also takes a `MaxTokens` that keeps track of a limit to the amount of tokens that can be delegated/undelegated/redelegated. If left empty, the amount is unlimited. Additionally, this Msg takes an `AllowList` and a `DenyList`, which allows you to select which validators you allow grantees to stake with. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/staking/v1beta1/authz.proto#L11-L31 -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/x/staking/types/authz.go#L18-L38 ## Gas diff --git a/x/authz/spec/02_state.md b/x/authz/spec/02_state.md index 2a7e3aa403b9..4aa7ac143234 100644 --- a/x/authz/spec/02_state.md +++ b/x/authz/spec/02_state.md @@ -12,4 +12,4 @@ Grants are identified by combining granter address (the address bytes of the gra The grant object encapsulates an `Authorization` type and an expiration timestamp: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/authz.proto#L21-L26 diff --git a/x/authz/spec/03_messages.md b/x/authz/spec/03_messages.md index e4da7203b507..22007980a226 100644 --- a/x/authz/spec/03_messages.md +++ b/x/authz/spec/03_messages.md @@ -11,7 +11,7 @@ In this section we describe the processing of messages for the authz module. An authorization grant is created using the `MsgGrant` message. If there is already a grant for the `(granter, grantee, Authorization)` triple, then the new grant overwrites the previous one. To update or extend an existing grant, a new grant with the same `(granter, grantee, Authorization)` triple should be created. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/tx.proto#L32-L37 The message handling should fail if: @@ -24,7 +24,7 @@ The message handling should fail if: A grant can be removed with the `MsgRevoke` message. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/tx.proto#L60-L64 The message handling should fail if: @@ -37,7 +37,7 @@ NOTE: The `MsgExec` message removes a grant if the grant has expired. When a grantee wants to execute a transaction on behalf of a granter, they must send `MsgExec`. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-beta1/proto/cosmos/authz/v1beta1/tx.proto#L47-L53 The message handling should fail if: diff --git a/x/bank/spec/03_messages.md b/x/bank/spec/03_messages.md index 23590bf00c74..6e2913d34d76 100644 --- a/x/bank/spec/03_messages.md +++ b/x/bank/spec/03_messages.md @@ -7,7 +7,7 @@ order: 3 ## MsgSend Send coins from one address to another. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/bank/v1beta1/tx.proto#L19-L28 The message will fail under the following conditions: @@ -17,7 +17,7 @@ The message will fail under the following conditions: ## MsgMultiSend Send coins from and to a series of different address. If any of the receiving addresses do not correspond to an existing account, a new account is created. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/bank/v1beta1/tx.proto#L33-L39 The message will fail under the following conditions: diff --git a/x/crisis/spec/02_messages.md b/x/crisis/spec/02_messages.md index c06d56aac344..7df7a62bb1e9 100644 --- a/x/crisis/spec/02_messages.md +++ b/x/crisis/spec/02_messages.md @@ -11,7 +11,7 @@ corresponding updates to the state. Blockchain invariants can be checked using the `MsgVerifyInvariant` message. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc7/proto/cosmos/crisis/v1beta1/tx.proto#L14-L22 This message is expected to fail if: diff --git a/x/distribution/spec/02_state.md b/x/distribution/spec/02_state.md index 06e0f5b125ca..2e91b52f4437 100644 --- a/x/distribution/spec/02_state.md +++ b/x/distribution/spec/02_state.md @@ -27,7 +27,7 @@ type DecCoin struct { } ``` -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/distribution/v1beta1/distribution.proto#L94-L101 ## Validator Distribution diff --git a/x/distribution/spec/04_messages.md b/x/distribution/spec/04_messages.md index 74bf027c6c80..b9b0b9d32e23 100644 --- a/x/distribution/spec/04_messages.md +++ b/x/distribution/spec/04_messages.md @@ -13,7 +13,7 @@ The withdraw address cannot be any of the module accounts. These accounts are bl Response: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.4/proto/cosmos/distribution/v1beta1/tx.proto#L29-L37 ```go func (k Keeper) SetWithdrawAddr(ctx sdk.Context, delegatorAddr sdk.AccAddress, withdrawAddr sdk.AccAddress) error @@ -63,7 +63,7 @@ The final calculated stake is equivalent to the actual staked coins in the deleg Response: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.4/proto/cosmos/distribution/v1beta1/tx.proto#L42-L50 ## WithdrawValidatorCommission diff --git a/x/feegrant/spec/01_concepts.md b/x/feegrant/spec/01_concepts.md index a7b7de00ad7b..a4571f8a9d13 100644 --- a/x/feegrant/spec/01_concepts.md +++ b/x/feegrant/spec/01_concepts.md @@ -8,11 +8,11 @@ order: 1 `Grant` is stored in the KVStore to record a grant with full context. Every grant will contain `granter`, `grantee` and what kind of `allowance` is granted. `granter` is an account address who is giving permission to `grantee` (the beneficiary account address) to pay for some or all of `grantee`'s transaction fees. `allowance` defines what kind of fee allowance (`BasicAllowance` or `PeriodicAllowance`, see below) is granted to `grantee`. `allowance` accepts an interface which implements `FeeAllowanceI`, encoded as `Any` type. There can be only one existing fee grant allowed for a `grantee` and `granter`, self grants are not allowed. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/feegrant.proto#L75-L81 `FeeAllowanceI` looks like: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/x/feegrant/fees.go#L9-L32 ## Fee Allowance types @@ -25,7 +25,7 @@ There are two types of fee allowances present at the moment: `BasicAllowance` is permission for `grantee` to use fee from a `granter`'s account. If any of the `spend_limit` or `expiration` reaches its limit, the grant will be removed from the state. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/feegrant.proto#L13-L26 * `spend_limit` is the limit of coins that are allowed to be used from the `granter` account. If it is empty, it assumes there's no spend limit, `grantee` can use any number of available tokens from `granter` account address before the expiration. @@ -37,7 +37,7 @@ There are two types of fee allowances present at the moment: `PeriodicAllowance` is a repeating fee allowance for the mentioned period, we can mention when the grant can expire as well as when a period can reset. We can also define the maximum number of coins that can be used in a mentioned period of time. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/feegrant.proto#L28-L73 * `basic` is the instance of `BasicAllowance` which is optional for periodic fee allowance. If empty, the grant will have no `expiration` and no `spend_limit`. @@ -53,13 +53,13 @@ There are two types of fee allowances present at the moment: `feegrant` module introduces a `FeeGranter` flag for CLI for the sake of executing transactions with fee granter. When this flag is set, `clientCtx` will append the granter account address for transactions generated through CLI. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/client/cmd.go#L224-L235 -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/client/tx/tx.go#L120 -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/x/auth/tx/builder.go#L268-L277 -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/proto/cosmos/tx/v1beta1/tx.proto#L160-L181 Example cmd: diff --git a/x/feegrant/spec/02_state.md b/x/feegrant/spec/02_state.md index ce2b50958566..0c5b9177d1f9 100644 --- a/x/feegrant/spec/02_state.md +++ b/x/feegrant/spec/02_state.md @@ -12,7 +12,7 @@ Fee allowance grants are stored in the state as follows: * Grant: `0x00 | grantee_addr_len (1 byte) | grantee_addr_bytes | granter_addr_len (1 byte) | granter_addr_bytes -> ProtocolBuffer(Grant)` -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/x/feegrant/feegrant.pb.go#L221-L229 ## FeeAllowanceQueue diff --git a/x/feegrant/spec/03_messages.md b/x/feegrant/spec/03_messages.md index 133112a5f8b2..602dd2b7125a 100644 --- a/x/feegrant/spec/03_messages.md +++ b/x/feegrant/spec/03_messages.md @@ -8,10 +8,10 @@ order: 3 A fee allowance grant will be created with the `MsgGrantAllowance` message. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/tx.proto#L22-L33 ## Msg/RevokeAllowance An allowed grant fee allowance can be removed with the `MsgRevokeAllowance` message. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/691032b8be0f7539ec99f8882caecefc51f33d1f/proto/cosmos/feegrant/v1beta1/tx.proto#L38-L45 diff --git a/x/gov/spec/01_concepts.md b/x/gov/spec/01_concepts.md index 2168b0f2d571..c1e3ed830dea 100644 --- a/x/gov/spec/01_concepts.md +++ b/x/gov/spec/01_concepts.md @@ -124,9 +124,9 @@ Often times the entity owning that address might not be a single individual. For To represent weighted vote on chain, we use the following Protobuf message. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-alpha1/proto/cosmos/gov/v1beta1/gov.proto#L32-L40 -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.43.0-alpha1/proto/cosmos/gov/v1beta1/gov.proto#L126-L137 For a weighted vote to be valid, the `options` field must not contain duplicate vote options, and the sum of weights of all options must be equal to 1. diff --git a/x/gov/spec/02_state.md b/x/gov/spec/02_state.md index 6e648f0a26a1..06e1e6908e9e 100644 --- a/x/gov/spec/02_state.md +++ b/x/gov/spec/02_state.md @@ -12,7 +12,7 @@ to resolve and then execute if the proposal passes. `Proposal`'s are identified unique id and contains a series of timestamps: `submit_time`, `deposit_end_time`, `voting_start_time`, `voting_end_time` which track the lifecycle of a proposal -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/4a129832eb16f37a89e97652a669f0cdc9196ca9/proto/cosmos/gov/v1beta2/gov.proto#L42-L52 A proposal will generally require more than just a set of messages to explain its purpose but need some greater justification and allow a means for interested participants @@ -58,15 +58,15 @@ parameter set has to be created and the previous one rendered inactive. ### DepositParams -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L127-L145 ### VotingParams -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L147-L156 ### TallyParams -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L158-L183 Parameters are stored in a global `GlobalParams` KVStore. @@ -104,7 +104,7 @@ const ( ## Deposit -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/gov.proto#L43-L53 ## ValidatorGovInfo diff --git a/x/gov/spec/03_messages.md b/x/gov/spec/03_messages.md index 69d095903435..04fcbf1d9d69 100644 --- a/x/gov/spec/03_messages.md +++ b/x/gov/spec/03_messages.md @@ -9,7 +9,7 @@ order: 3 Proposals can be submitted by any account via a `MsgSubmitProposal` transaction. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/ab9545527d630fe38761aa61cc5c95eabd68e0e6/proto/cosmos/gov/v1beta2/tx.proto#L34-L44 All `sdk.Msgs` passed into the `messages` field of a `MsgSubmitProposal` message must be registered in the app's `MsgServiceRouter`. Each of these messages must @@ -78,7 +78,7 @@ Once a proposal is submitted, if `Proposal.TotalDeposit < ActiveParam.MinDeposit`, Atom holders can send `MsgDeposit` transactions to increase the proposal's deposit. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/tx.proto#L61-L72 **State modifications:** @@ -144,7 +144,7 @@ Once `ActiveParam.MinDeposit` is reached, voting period starts. From there, bonded Atom holders are able to send `MsgVote` transactions to cast their vote on the proposal. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/gov/v1beta1/tx.proto#L46-L56 **State modifications:** diff --git a/x/group/internal/orm/spec/01_table.md b/x/group/internal/orm/spec/01_table.md index 53fc6be1eba0..7e7237f9d054 100644 --- a/x/group/internal/orm/spec/01_table.md +++ b/x/group/internal/orm/spec/01_table.md @@ -2,7 +2,7 @@ A table can be built given a `codec.ProtoMarshaler` model type, a prefix to access the underlying prefix store used to store table data as well as a `Codec` for marshalling/unmarshalling. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/table.go#L24-L30 In the prefix store, entities should be stored by an unique identifier called `RowID` which can be based either on an `uint64` auto-increment counter, string or dynamic size bytes. Regular CRUD operations can be performed on a table, these methods take a `sdk.KVStore` as parameter to get the table prefix store. @@ -21,7 +21,7 @@ The `table` struct is private, so that we only have custom tables built on top o `AutoUInt64Table` is a table type with an auto incrementing `uint64` ID. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/auto_uint64.go#L11-L14 It's based on the `Sequence` struct which is a persistent unique key generator based on a counter encoded using 8 byte big endian. @@ -33,7 +33,7 @@ It's based on the `Sequence` struct which is a persistent unique key generator b The model provided for creating a `PrimaryKeyTable` should implement the `PrimaryKeyed` interface: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/9f78f16ae75cc42fc5fe636bde18a453ba74831f/x/group/internal/orm/primary_key.go#L28-L41 `PrimaryKeyFields()` method returns the list of key parts for a given object. The primary key parts can be []byte, string, and `uint64` types. diff --git a/x/group/internal/orm/spec/02_secondary_index.md b/x/group/internal/orm/spec/02_secondary_index.md index 74742faf8249..fd25a606f571 100644 --- a/x/group/internal/orm/spec/02_secondary_index.md +++ b/x/group/internal/orm/spec/02_secondary_index.md @@ -2,19 +2,19 @@ Secondary indexes can be used on `Indexable` [tables](01_table.md). Indeed, those tables implement the `Indexable` interface that provides a set of functions that can be called by indexes to register and interact with the tables, like callback functions that are called on entries creation, update or deletion to create, update or remove corresponding entries in the table secondary indexes. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/types.go#L88-L92 ## MultiKeyIndex A `MultiKeyIndex` is an index where multiple entries can point to the same underlying object. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L25-L31 Internally, it uses an `Indexer` that manages the persistence of the index based on searchable keys and create/update/delete operations. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L15-L19 -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/indexer.go#L15-L18 The currently used implementation of an `indexer`, `Indexer`, relies on an `IndexerFunc` that should be provided when instantiating the index. Based on the source object, this function returns one or multiple index keys as `[]interface{}`. Such secondary index keys should be bytes, string or `uint64` in order to be handled properly by the [key codec](01_table.md#key-codec) which defines specific encoding for those types. In the index prefix store, the keys are built based on the source object's `RowID` and its secondary index key(s) using the key codec and the values are set as empty bytes. diff --git a/x/group/internal/orm/spec/03_iterator_pagination.md b/x/group/internal/orm/spec/03_iterator_pagination.md index f7fda6393f32..ac0839623321 100644 --- a/x/group/internal/orm/spec/03_iterator_pagination.md +++ b/x/group/internal/orm/spec/03_iterator_pagination.md @@ -6,15 +6,15 @@ Both [tables](01_table.md) and [secondary indexes](02_secondary_index.md) suppor An `Iterator` allows iteration through a sequence of key value pairs. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/types.go#L77-L83 Tables rely on a `typeSafeIterator` that is used by `PrefixScan` and `ReversePrefixScan` `table` methods to iterate through a range of `RowID`s. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/table.go#235-L239 Secondary indexes rely on an `indexIterator` that can strip the `RowID` from the full index key in order to get the underlying value in the table prefix store. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/index.go#L227-L232 Under the hood, both use a prefix store `Iterator` (alias for tm-db `Iterator`). @@ -23,6 +23,6 @@ Under the hood, both use a prefix store `Iterator` (alias for tm-db `Iterator`). The `Paginate` function does pagination given an [`Iterator`](#iterator) and a `query.PageRequest`, and returns a `query.PageResponse`. It unmarshals the results into the provided dest interface that should be a pointer to a slice of models. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/430163ed4eefcc0d67b706411ffc0b7c5414cd90/x/group/internal/orm/iterator.go#L117-L216 Secondary indexes have a `GetPaginated` method that returns an `Iterator` for the given searched secondary index key, starting from the `query.PageRequest` key if provided. It's important to note that this `query.PageRequest` key should be a `RowID` (that could have been returned by a previous paginated request). The returned `Iterator` can then be used with the `Paginate` function and the same `query.PageRequest`. diff --git a/x/group/spec/03_messages.md b/x/group/spec/03_messages.md index 813e199adb82..ca20eeaeaf4c 100644 --- a/x/group/spec/03_messages.md +++ b/x/group/spec/03_messages.md @@ -11,7 +11,7 @@ A new group can be created with the `MsgCreateGroup`, which has an admin address The metadata has a maximum length that is chosen by the app developer, and passed into the group keeper as a config. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L54-L65 It's expecting to fail if metadata length is greater than `MaxMetadataLen` config. @@ -19,7 +19,7 @@ It's expecting to fail if metadata length is greater than `MaxMetadataLen` confi Group members can be updated with the `UpdateGroupMembers`. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L74-L86 In the list of `MemberUpdates`, an existing member can be removed by setting its weight to 0. @@ -29,7 +29,7 @@ It's expecting to fail if the signer is not the admin of the group. The `UpdateGroupAdmin` can be used to update a group admin. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L91-L102 It's expecting to fail if the signer is not the admin of the group. @@ -37,7 +37,7 @@ It's expecting to fail if the signer is not the admin of the group. The `UpdateGroupMetadata` can be used to update a group metadata. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L107-L118 It's expecting to fail if: @@ -48,7 +48,7 @@ It's expecting to fail if: A new group policy can be created with the `MsgCreateGroupPolicy`, which has an admin address, a group id, a decision policy and some optional metadata bytes. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L121-L142 It's expecting to fail if metadata length is greater than `MaxMetadataLen` config. @@ -56,7 +56,7 @@ It's expecting to fail if metadata length is greater than `MaxMetadataLen` confi The `UpdateGroupPolicyAdmin` can be used to update a group policy admin. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L151-L162 It's expecting to fail if the signer is not the admin of the group policy. @@ -64,7 +64,7 @@ It's expecting to fail if the signer is not the admin of the group policy. The `UpdateGroupPolicyDecisionPolicy` can be used to update a decision policy. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L167-L179 It's expecting to fail if the signer is not the admin of the group policy. @@ -72,7 +72,7 @@ It's expecting to fail if the signer is not the admin of the group policy. The `UpdateGroupPolicyMetadata` can be used to update a group policy metadata. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L184-L195 It's expecting to fail if: @@ -84,7 +84,7 @@ It's expecting to fail if: A new proposal can be created with the `MsgCreateProposal`, which has a group policy account address, a list of proposers addresses, a list of messages to execute if the proposal is accepted and some optional metadata bytes. An optional `Exec` value can be provided to try to execute the proposal immediately after proposal creation. Proposers signatures are considered as yes votes in this case. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L218-L239 It's expecting to fail if metadata length is greater than `MaxMetadataLen` config. @@ -92,7 +92,7 @@ It's expecting to fail if metadata length is greater than `MaxMetadataLen` confi A proposal can be withdrawn using `MsgWithdrawProposal` which has a `address` (can be either proposer or policy admin) and a `proposal_id` (which has to be withdrawn). -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/f2d6f0e4bb1a9bd7f7ae3cdc4702c9d3d1fc0329/proto/cosmos/group/v1beta1/tx.proto#L251-L258 It's expecting to fail if: @@ -104,7 +104,7 @@ It's expecting to fail if: A new vote can be created with the `MsgVote`, given a proposal id, a voter address, a choice (yes, no, veto or abstain) and some optional metadata bytes. An optional `Exec` value can be provided to try to execute the proposal immediately after voting. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L248-L265 It's expecting to fail if metadata length is greater than `MaxMetadataLen` config. @@ -112,7 +112,7 @@ It's expecting to fail if metadata length is greater than `MaxMetadataLen` confi A proposal can be executed with the `MsgExec`. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/6f58963e7f6ce820e9b33f02f06f7b96f6d2e347/proto/cosmos/group/v1beta1/tx.proto#L270-L278 The messages that are part of this proposal won't be executed if: diff --git a/x/mint/spec/02_state.md b/x/mint/spec/02_state.md index 0d336b93c28a..b5acd5264846 100644 --- a/x/mint/spec/02_state.md +++ b/x/mint/spec/02_state.md @@ -10,7 +10,7 @@ The minter is a space for holding current inflation information. * Minter: `0x00 -> ProtocolBuffer(minter)` -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc7/proto/cosmos/mint/v1beta1/mint.proto#L8-L19 ## Params @@ -18,4 +18,4 @@ Minting params are held in the global params store. * Params: `mint/params -> legacy_amino(params)` -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0-rc7/proto/cosmos/mint/v1beta1/mint.proto#L21-L53 diff --git a/x/slashing/spec/02_state.md b/x/slashing/spec/02_state.md index 3b20da035da0..a0298b57499e 100644 --- a/x/slashing/spec/02_state.md +++ b/x/slashing/spec/02_state.md @@ -48,4 +48,4 @@ bonded validator. The `SignedBlocksWindow` parameter defines the size The information stored for tracking validator liveness is as follows: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/slashing/v1beta1/slashing.proto#L11-L33 diff --git a/x/staking/spec/01_state.md b/x/staking/spec/01_state.md index 5b1226a9a890..1dad2be91780 100644 --- a/x/staking/spec/01_state.md +++ b/x/staking/spec/01_state.md @@ -22,7 +22,7 @@ and defines overall functioning of the staking module. * Params: `Paramsspace("staking") -> legacy_amino(params)` -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.1/proto/cosmos/staking/v1beta1/staking.proto#L230-L241 ## Validator @@ -75,9 +75,9 @@ is updated during the validator set update process which takes place in [`EndBlo Each validator's state is stored in a `Validator` struct: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L65-L99 -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L24-L63 ## Delegation @@ -91,7 +91,7 @@ funds are held in a `Delegation` data structure. It is owned by one delegator, and is associated with the shares for one validator. The sender of the transaction is the owner of the bond. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L159-L170 ### Delegator Shares @@ -130,7 +130,7 @@ slashed. A UnbondingDelegation object is created every time an unbonding is initiated. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L172-L198 ## Redelegation @@ -158,7 +158,7 @@ A redelegation object is created every time a redelegation occurs. To prevent * and, the (re)delegator is attempting to create a _new_ redelegation where the source validator for this new redelegation is `Validator X`. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L200-L228 ## Queues @@ -180,7 +180,7 @@ delegations queue is kept. * UnbondingDelegation: `0x41 | format(time) -> []DVPair` -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L123-L133 ### RedelegationQueue @@ -189,7 +189,7 @@ kept. * RedelegationQueue: `0x42 | format(time) -> []DVVTriplet` -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L140-L152 ### ValidatorQueue @@ -208,7 +208,7 @@ that multiple validators exist in the queue at the same location. HistoricalInfo objects are stored and pruned at each block such that the staking keeper persists the `n` most recent historical info defined by staking module parameter: `HistoricalEntries`. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L15-L22 At each BeginBlock, the staking keeper will persist the current Header and the Validators that committed the current block in a `HistoricalInfo` object. The Validators are sorted on their address to ensure that diff --git a/x/staking/spec/03_messages.md b/x/staking/spec/03_messages.md index 7dceb7626511..27c307b24994 100644 --- a/x/staking/spec/03_messages.md +++ b/x/staking/spec/03_messages.md @@ -11,9 +11,9 @@ In this section we describe the processing of the staking messages and the corre A validator is created using the `MsgCreateValidator` message. The validator must be created with an initial delegation from the operator. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L16-L17 -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L35-L51 This message is expected to fail if: @@ -36,9 +36,9 @@ in the first end-block. The `Description`, `CommissionRate` of a validator can be updated using the `MsgEditValidator` message. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L19-L20 -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L56-L76 This message is expected to fail if: @@ -55,9 +55,9 @@ Within this message the delegator provides coins, and in return receives some amount of their validator's (newly created) delegator-shares that are assigned to `Delegation.Shares`. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L22-L24 -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L81-L90 This message is expected to fail if: @@ -87,13 +87,13 @@ will not be added to the power index until it is unjailed. The `MsgUndelegate` message allows delegators to undelegate their tokens from validator. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L30-L32 -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L112-L121 This message returns a response containing the completion time of the undelegation: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L123-L126 This message is expected to fail if: @@ -122,13 +122,13 @@ The redelegation command allows delegators to instantly switch validators. Once the unbonding period has passed, the redelegation is automatically completed in the EndBlocker. -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L26-L28 -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L95-L105 This message returns a response containing the completion time of the redelegation: -+++ ++++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L107-L110 This message is expected to fail if: