Skip to content

Commit

Permalink
docs: updates outdated docs (cosmos#12014)
Browse files Browse the repository at this point in the history
  • Loading branch information
julienrbrt authored May 31, 2022
1 parent 3504dd3 commit b0756f2
Show file tree
Hide file tree
Showing 89 changed files with 433 additions and 819 deletions.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ parent:
<img alt="License: Apache-2.0" src="https://img.shields.io/github/license/cosmos/cosmos-sdk.svg" />
</a>
<a href="https://pkg.go.dev/github.com/cosmos/cosmos-sdk?tab=doc">
<img alt="GoDoc" src="https://godoc.org/github.com/cosmos/cosmos-sdk?status.svg" />
<img alt="GoDoc" src="https://pkg.go.dev/github.com/cosmos/cosmos-sdk?status.svg" />
</a>
<a href="https://goreportcard.com/report/github.com/cosmos/cosmos-sdk">
<img alt="Go report card" src="https://goreportcard.com/badge/github.com/cosmos/cosmos-sdk" />
Expand Down
4 changes: 2 additions & 2 deletions RELEASE_PROCESS.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ To smoothen the update to the latest stable release, the SDK includes a set of C
### What does not qualify as SRU

* State machine changes.
* Breaking changes in Protobuf definitions, as specified in [ADR-044](./docs/architecture/adr-044-protobuf-updates-guidelines.md).
* Breaking changes in Protobuf definitions, as specified in [ADR-044](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-044-protobuf-updates-guidelines.md).
* Changes that introduces API breakages (e.g. public functions and interfaces removal/renaming).
* Client-breaking changes in gRPC and HTTP request and response types.
* CLI-breaking changes.
Expand All @@ -149,7 +149,7 @@ Pull requests that fix bugs and add features that fall in the following categori
As rule of thumb, the following changes will **NOT** be automatically accepted into stable point-releases:

* **State machine changes**.
* **Protobug-breaking changes**, as specified in [ADR-044](./docs/architecture/adr-044-protobuf-updates- guidelines.md).
* **Protobug-breaking changes**, as specified in [ADR-044](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-044-protobuf-updates- guidelines.md).
* **Client-breaking changes**, i.e. changes that prevent gRPC, HTTP and RPC clients to continue interacting with the node without any change.
* **API-breaking changes**, i.e. changes that prevent client applications to _build without modifications_ to the client application's source code.
* **CLI-breaking changes**, i.e. changes that require usage changes for CLI users.
Expand Down
2 changes: 1 addition & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ this [blog post](https://blog.cosmos.network/bug-bounty-program-for-tendermint-c

The following is a list of examples of the kinds of bugs we're most interested
in for the Cosmos SDK. See [here](https://github.com/tendermint/tendermint/blob/master/SECURITY.md) for vulnerabilities we are interested
in for Tendermint and other lower-level libraries (eg. [IAVL](https://github.com/tendermint/iavl)).
in for Tendermint and other lower-level libraries (eg. [IAVL](https://github.com/cosmos/iavl)).

### Core packages

Expand Down
6 changes: 5 additions & 1 deletion docs/.vuepress/config.js
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,10 @@ module.exports = {
"label": "v0.45",
"key": "v0.45"
},
{
"label": "v0.46",
"key": "v0.46"
},
{
"label": "main",
"key": "main"
Expand Down Expand Up @@ -76,7 +80,7 @@ module.exports = {
},
{
title: "SDK API Reference",
path: "https://godoc.org/github.com/cosmos/cosmos-sdk"
path: "https://pkg.go.dev/github.com/cosmos/cosmos-sdk"
},
{
title: "REST API Spec",
Expand Down
2 changes: 1 addition & 1 deletion docs/DOCS_README.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ We are using [Algolia](https://www.algolia.com) to power full-text search. This
## Consistency

Because the build processes are identical (as is the information contained herein), this file should be kept in sync as
much as possible with its [counterpart in the Tendermint Core repo](https://github.com/tendermint/tendermint/blob/v0.34.0/docs/DOCS_README.md).
much as possible with its [counterpart in the Tendermint Core repo](https://github.com/tendermint/tendermint/blob/master/docs/DOCS_README.md).

### Update and Build the RPC docs

Expand Down
2 changes: 1 addition & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ aside: false

* **[Module Directory](../x/)**: Cosmos SDK module implementations and their respective documentation.
* **[Specifications](./spec/)**: Specifications of modules and other parts of the Cosmos SDK.
* **[Cosmos SDK API Reference](https://godoc.org/github.com/cosmos/cosmos-sdk)**: Godocs of the Cosmos SDK.
* **[Cosmos SDK API Reference](https://pkg.go.dev/github.com/cosmos/cosmos-sdk)**: Godocs of the Cosmos SDK.
* **[REST and RPC Endpoints](https://cosmos.network/rpc/)**: List of endpoints to interact with a `gaia` full-node.
* **[Rosetta API](./run-node/rosetta.md)**: Rosetta API integration.

Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/adr-010-modular-antehandler.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ For example, let's say a user wants to implement some custom signature verificat

### Per-Module AnteHandler

One approach is to use the [ModuleManager](https://godoc.org/github.com/cosmos/cosmos-sdk/types/module) and have each module implement its own antehandler if it requires custom antehandler logic. The ModuleManager can then be passed in an AnteHandler order in the same way it has an order for BeginBlockers and EndBlockers. The ModuleManager returns a single AnteHandler function that will take in a tx and run each module's `AnteHandle` in the specified order. The module manager's AnteHandler is set as the baseapp's AnteHandler.
One approach is to use the [ModuleManager](https://pkg.go.dev/github.com/cosmos/cosmos-sdk/types/module) and have each module implement its own antehandler if it requires custom antehandler logic. The ModuleManager can then be passed in an AnteHandler order in the same way it has an order for BeginBlockers and EndBlockers. The ModuleManager returns a single AnteHandler function that will take in a tx and run each module's `AnteHandle` in the specified order. The module manager's AnteHandler is set as the baseapp's AnteHandler.

Pros:

Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/adr-019-protobuf-state-encoding.md
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,7 @@ and client developer UX.

### Safe usage of `Any`

By default, the [gogo protobuf implementation of `Any`](https://godoc.org/github.com/gogo/protobuf/types)
By default, the [gogo protobuf implementation of `Any`](https://pkg.go.dev/github.com/gogo/protobuf/types)
uses [global type registration]( https://github.com/gogo/protobuf/blob/master/proto/properties.go#L540)
to decode values packed in `Any` into concrete
go types. This introduces a vulnerability where any malicious module
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/adr-022-custom-panic-handling.md
Original file line number Diff line number Diff line change
Expand Up @@ -215,4 +215,4 @@ This method would prepend handlers to an existing chain.
## References

* [PR-6053 with proposed solution](https://github.com/cosmos/cosmos-sdk/pull/6053)
* [Similar solution. ADR-010 Modular AnteHandler](https://github.com/cosmos/cosmos-sdk/blob/v0.38.3/docs/architecture/adr-010-modular-antehandler.md)
* [Similar solution. ADR-010 Modular AnteHandler](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-010-modular-antehandler.md)
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ the same serialization of a `SignDoc` as defined in
serialization.

Currently, for block signatures we are using a workaround: we create a new [TxRaw](https://github.com/cosmos/cosmos-sdk/blob/9e85e81e0e8140067dd893421290c191529c148c/proto/cosmos/tx/v1beta1/tx.proto#L30)
instance (as defined in [adr-020-protobuf-transaction-encoding](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-020-protobuf-transaction-encoding.md#transactions))
instance (as defined in [adr-020-protobuf-transaction-encoding](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-020-protobuf-transaction-encoding.md#transactions))
by converting all [Tx](https://github.com/cosmos/cosmos-sdk/blob/9e85e81e0e8140067dd893421290c191529c148c/proto/cosmos/tx/v1beta1/tx.proto#L13)
fields to bytes on the client side. This adds an additional manual
step when sending and signing transactions.
Expand Down
4 changes: 2 additions & 2 deletions docs/architecture/adr-033-protobuf-inter-module-comm.md
Original file line number Diff line number Diff line change
Expand Up @@ -165,7 +165,7 @@ corresponding "public key". From the [ADR 028](./adr-028-public-key-addresses.md
or derived accounts that can be used for different pools (ex. staking pools) or managed accounts (ex. group
accounts). We can also think of module sub-accounts as similar to derived keys - there is a root key and then some
derivation path. `ModuleID` is a simple struct which contains the module name and optional "derivation" path,
and forms its address based on the `AddressHash` method from [the ADR-028](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-028-public-key-addresses.md):
and forms its address based on the `AddressHash` method from [the ADR-028](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-028-public-key-addresses.md):

```go
type ModuleID struct {
Expand Down Expand Up @@ -330,7 +330,7 @@ ADR.
### Authorization

By default, the inter-module router requires that messages are sent by the first signer returned by `GetSigners`. The
inter-module router should also accept authorization middleware such as that provided by [ADR 030](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-030-authz-module.md).
inter-module router should also accept authorization middleware such as that provided by [ADR 030](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-030-authz-module.md).
This middleware will allow accounts to otherwise specific module accounts to perform actions on their behalf.
Authorization middleware should take into account the need to grant certain modules effectively "admin" privileges to
other modules. This will be addressed in separate ADRs or updates to this ADR.
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/adr-043-nft-module.md
Original file line number Diff line number Diff line change
Expand Up @@ -337,4 +337,4 @@ Other networks in the Cosmos ecosystem could design and implement their own NFT

* 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)
* [ADR 033](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-033-protobuf-inter-module-comm.md)
20 changes: 10 additions & 10 deletions docs/basics/accounts.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,9 +66,9 @@ In the node, all data is stored using Protocol Buffers serialization.

The Cosmos SDK supports the following digital key schemes for creating digital signatures:

* `secp256k1`, as implemented in the [Cosmos SDK's `crypto/keys/secp256k1` package](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/keys/secp256k1/secp256k1.go).
* `secp256r1`, as implemented in the [Cosmos SDK's `crypto/keys/secp256r1` package](https://github.com/cosmos/cosmos-sdk/blob/master/crypto/keys/secp256r1/pubkey.go),
* `tm-ed25519`, as implemented in the [Cosmos SDK `crypto/keys/ed25519` package](https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/crypto/keys/ed25519/ed25519.go). This scheme is supported only for the consensus validation.
* `secp256k1`, as implemented in the [Cosmos SDK's `crypto/keys/secp256k1` package](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/crypto/keys/secp256k1/secp256k1.go).
* `secp256r1`, as implemented in the [Cosmos SDK's `crypto/keys/secp256r1` package](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/crypto/keys/secp256r1/pubkey.go),
* `tm-ed25519`, as implemented in the [Cosmos SDK `crypto/keys/ed25519` package](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/crypto/keys/ed25519/ed25519.go). This scheme is supported only for the consensus validation.

| | Address length in bytes | Public key length in bytes | Used for transaction authentication | Used for consensus (tendermint) |
| :----------: | :---------------------: | :------------------------: | :---------------------------------: | :-----------------------------: |
Expand All @@ -88,9 +88,9 @@ 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
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/address.go#L108-L125

Address construction algorithm is defined in [ADR-28](https://github.com/cosmos/cosmos-sdk/blob/master/docs/architecture/adr-028-public-key-addresses.md).
Address construction algorithm is defined in [ADR-28](https://github.com/cosmos/cosmos-sdk/blob/main/docs/architecture/adr-028-public-key-addresses.md).
Here is the standard way to obtain an account address from a `pub` public key:

```go
Expand All @@ -101,7 +101,7 @@ Of note, the `Marshal()` and `Bytes()` method both return the same raw `[]byte`

For user interaction, addresses are formatted using [Bech32](https://en.bitcoin.it/wiki/Bech32) and implemented by the `String` method. The Bech32 method is the only supported format to use when interacting with a blockchain. The Bech32 human-readable part (Bech32 prefix) is used to denote an address type. Example:

+++ https://github.com/cosmos/cosmos-sdk/blob/v0.42.1/types/address.go#L230-L244
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/types/address.go#L272-L286

| | Address Bech32 Prefix |
| ------------------ | --------------------- |
Expand All @@ -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
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/crypto/types/types.go#L8-L17

A compressed format is used for `secp256k1` and `secp256r1` serialization.

Expand All @@ -123,15 +123,15 @@ A compressed format is used for `secp256k1` and `secp256r1` serialization.
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:
For user interactions, `PubKey` is formatted using Protobufs JSON ([ProtoMarshalJSON](https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/codec/json.go#L14-L34) function). Example:

+++ https://github.com/cosmos/cosmos-sdk/blob/7568b66/crypto/keyring/output.go#L23-L39
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/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.46.0-rc1/crypto/keyring/keyring.go#L53-L101
+++ https://github.com/cosmos/cosmos-sdk/blob/v0.46.0-rc1/crypto/keyring/keyring.go#L54-L101

The default implementation of `Keyring` comes from the third-party [`99designs/keyring`](https://github.com/99designs/keyring) library.

Expand Down
Loading

0 comments on commit b0756f2

Please sign in to comment.