Skip to content

Commit

Permalink
chore: upate documenation from cosmos-sdk/docs (#134)
Browse files Browse the repository at this point in the history
chore: Sync docs from cosmos-sdk/docs

Co-authored-by: samricotta <[email protected]>
  • Loading branch information
github-actions[bot] and samricotta authored Apr 11, 2024
1 parent a300ced commit cdf5b49
Show file tree
Hide file tree
Showing 96 changed files with 2,703 additions and 535 deletions.
10 changes: 5 additions & 5 deletions docs/build/abci/00-introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

## What is ABCI?

ABC, Application Blockchain Interface is the interface between CometBFT and the application, more information about ABCI can be found [here](https://docs.cometbft.com/v0.38/spec/abci/). Within the release of ABCI 2.0 for the 0.38 CometBFT release there were additional methods introduced.
ABCI, Application Blockchain Interface is the interface between CometBFT and the application. More information about ABCI can be found in the specs [here](https://docs.cometbft.com/v0.38/spec/abci/). Within the release of ABCI 2.0 for the 0.38 CometBFT release there were additional methods introduced.

The 5 methods introduced during ABCI 2.0 are:
The 5 methods introduced during ABCI 2.0 (compared to ABCI v0) are:

* `PrepareProposal`
* `ProcessProposal`
Expand All @@ -17,11 +17,11 @@ The 5 methods introduced during ABCI 2.0 are:

## PrepareProposal

Based on their voting power, CometBFT chooses a block proposer and calls `PrepareProposal` on the block proposer's application (Cosmos SDK). The selected block proposer is responsible for collecting outstanding transactions from the mempool, adhering to the application's specifications. The application can enforce custom transaction ordering and incorporate additional transactions, potentially generated from vote extensions in the previous block.
Based on validator voting power, CometBFT chooses a block proposer and calls `PrepareProposal` on the block proposer's application (Cosmos SDK). The selected block proposer is responsible for collecting outstanding transactions from the mempool, adhering to the application's specifications. The application can enforce custom transaction ordering and incorporate additional transactions, potentially generated from vote extensions in the previous block.

To perform this manipulation on the application side, a custom handler must be implemented. By default, the Cosmos SDK provides `PrepareProposalHandler`, used in conjunction with an application specific mempool. A custom handler can be written by application developer, if a noop handler provided, all transactions are considered valid. Please see [this](https://github.com/fatal-fruit/abci-workshop) tutorial for more information on custom handlers.

Please note that vote extensions will only be available on the following height in which vote extensions are enabled. More information about vote extensions can be found [here](https://docs.cosmos.network/main/build/abci/03-vote-extensions.md).
Please note that vote extensions will only be available on the following height in which vote extensions are enabled. More information about vote extensions can be found [here](https://docs.cosmos.network/main/build/abci/vote-extensions).

After creating the proposal, the proposer returns it to CometBFT.

Expand All @@ -48,4 +48,4 @@ Additionally, applications must keep the vote extension data concise as it can d

## FinalizeBlock

`FinalizeBlock` is then called and is responsible for updating the state of the blockchain and making the block available to users
`FinalizeBlock` is then called and is responsible for updating the state of the blockchain and making the block available to users.
6 changes: 3 additions & 3 deletions docs/build/abci/01-prepare-proposal.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,12 +33,12 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/abci_utils.go
```

This default implementation can be overridden by the application developer in
favor of a custom implementation in [`app.go`](../building-apps/01-app-go-v2.md):
favor of a custom implementation in [`app.go`](https://docs.cosmos.network/main/build/building-apps/app-go-v2):

```go
prepareOpt := func(app *baseapp.BaseApp) {
abciPropHandler := baseapp.NewDefaultProposalHandler(mempool, app)
app.SetPrepareProposal(abciPropHandler.PrepareProposalHandler())
abciPropHandler := baseapp.NewDefaultProposalHandler(mempool, app)
app.SetPrepareProposal(abciPropHandler.PrepareProposalHandler()))
}

baseAppOptions = append(baseAppOptions, prepareOpt)
Expand Down
12 changes: 6 additions & 6 deletions docs/build/abci/02-process-proposal.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,14 @@

`ProcessProposal` handles the validation of a proposal from `PrepareProposal`,
which also includes a block header. Meaning, that after a block has been proposed
the other validators have the right to vote on a block. The validator in the
the other validators have the right to accept or reject that block. The validator in the
default implementation of `PrepareProposal` runs basic validity checks on each
transaction.

Note, `ProcessProposal` MAY NOT be non-deterministic, i.e. it must be deterministic.
This means if `ProcessProposal` panics or fails and we reject, all honest validator
processes will prevote nil and the CometBFT round will proceed again until a valid
proposal is proposed.
processes should reject (i.e., prevote nil). If so, then CometBFT will start a new round with a new block proposal, and the same cycle will happen with `PrepareProposal`
and `ProcessProposal` for the new proposal.

Here is the implementation of the default implementation:

Expand All @@ -18,14 +18,14 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.50.0-alpha.0/baseapp/abci_utils.go#
```

Like `PrepareProposal` this implementation is the default and can be modified by
the application developer in [`app.go`](../building-apps/01-app-go-v2.md). If you decide to implement
the application developer in [`app.go`](https://docs.cosmos.network/main/build/building-apps/app-go-v2). If you decide to implement
your own `ProcessProposal` handler, you must be sure to ensure that the transactions
provided in the proposal DO NOT exceed the maximum block gas and `maxtxbytes` (if set).

```go
processOpt := func(app *baseapp.BaseApp) {
abciPropHandler := baseapp.NewDefaultProposalHandler(mempool, app)
app.SetProcessProposal(abciPropHandler.ProcessProposalHandler())
abciPropHandler := baseapp.NewDefaultProposalHandler(mempool, app)
app.SetProcessProposal(abciPropHandler.ProcessProposalHandler())
}

baseAppOptions = append(baseAppOptions, processOpt)
Expand Down
5 changes: 2 additions & 3 deletions docs/build/abci/03-vote-extensions.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,7 @@ defined in ABCI++.

## Extend Vote

ABCI++ allows an application to extend a pre-commit vote with arbitrary data. This
process does NOT have to be deterministic, and the data returned can be unique to the
ABCI2.0 (colloquially called ABCI++) allows an application to extend a pre-commit vote with arbitrary data. This process does NOT have to be deterministic, and the data returned can be unique to the
validator process. The Cosmos SDK defines [`baseapp.ExtendVoteHandler`](https://github.com/cosmos/cosmos-sdk/blob/v0.50.1/types/abci.go#L26-L27):

```go
Expand All @@ -29,7 +28,7 @@ to consider the size of the vote extensions as they could increase latency in bl
production. See [here](https://github.com/cometbft/cometbft/blob/v0.38.0-rc1/docs/qa/CometBFT-QA-38.md#vote-extensions-testbed)
for more details.

Click [here](https://docs.cosmos.network/main/user/tutorials/vote-extensions) if you would like a walkthrough of how to implement vote extensions.
Click [here](https://docs.cosmos.network/main/build/abci/vote-extensions) if you would like a walkthrough of how to implement vote extensions.


## Verify Vote Extension
Expand Down
2 changes: 1 addition & 1 deletion docs/build/architecture/PROCESS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

## What is an ADR?

An ADR is a document to document an implementation and design that may or may not have been discussed in an RFC. While an RFC is meant to replace synchoronus communication in a distributed environment, an ADR is meant to document an already made decision. An ADR won't come with much of a communication overhead because the discussion was recorded in an RFC or a synchronous discussion. If the consensus came from a synchoronus discussion then a short excerpt should be added to the ADR to explain the goals.
An ADR is a document to document an implementation and design that may or may not have been discussed in an RFC. While an RFC is meant to replace synchronous communication in a distributed environment, an ADR is meant to document an already made decision. An ADR won't come with much of a communication overhead because the discussion was recorded in an RFC or a synchronous discussion. If the consensus came from a synchronous discussion then a short excerpt should be added to the ADR to explain the goals.

## ADR life cycle

Expand Down
4 changes: 2 additions & 2 deletions docs/build/architecture/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,8 @@ When writing ADRs, follow the same best practices for writing RFCs. When writing
* [ADR 058: Auto-Generated CLI](./adr-058-auto-generated-cli.md)
* [ADR 060: ABCI 1.0 (Phase I)](adr-060-abci-1.0.md)
* [ADR 061: Liquid Staking](./adr-061-liquid-staking.md)
* [ADR 070: Un-Ordered Transaction Inclusion](./adr-070-unordered-account.md)
* [ADR 070: Un-Ordered Transaction Inclusion](./adr-070-unordered-transactions.md)
* [ADR 065: Store v2](./adr-065-store-v2.md)

### Proposed

Expand All @@ -86,7 +87,6 @@ When writing ADRs, follow the same best practices for writing RFCs. When writing
* [ADR 059: Test Scopes](./adr-059-test-scopes.md)
* [ADR 062: Collections State Layer](./adr-062-collections-state-layer.md)
* [ADR 063: Core Module API](./adr-063-core-module-api.md)
* [ADR 065: Store v2](./adr-065-store-v2.md)
* [ADR 067: Simulator v2](./adr-067-simulator-v2.md)
* [ADR 069: `x/gov` modularity, multiple choice and optimisic proposals](./adr-069-gov-improvements.md)

Expand Down
2 changes: 1 addition & 1 deletion docs/build/architecture/_category_.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"label": "ADRs",
"position": 7,
"position": 6,
"link": null
}
14 changes: 7 additions & 7 deletions docs/build/architecture/adr-003-dynamic-capability-store.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,21 +85,21 @@ It MUST be called before `InitialiseAndSeal`.

```go
func (ck CapabilityKeeper) ScopeToModule(moduleName string) ScopedCapabilityKeeper {
if k.sealed {
if ck.sealed {
panic("cannot scope to module via a sealed capability keeper")
}

if _, ok := k.scopedModules[moduleName]; ok {
if _, ok := ck.scopedModules[moduleName]; ok {
panic(fmt.Sprintf("cannot create multiple scoped keepers for the same module name: %s", moduleName))
}

k.scopedModules[moduleName] = struct{}{}
ck.scopedModules[moduleName] = struct{}{}

return ScopedKeeper{
cdc: k.cdc,
storeKey: k.storeKey,
memKey: k.memKey,
capMap: k.capMap,
cdc: ck.cdc,
storeKey: ck.storeKey,
memKey: ck.memKey,
capMap: ck.capMap,
module: moduleName,
}
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,11 +34,11 @@ Also, it should be noted that this ADR includes only the simplest form of consen
* In current Tendermint design, consensus key rotations are seen as power changes from LCD or IBC perspective
* Therefore, to minimize unnecessary frequent key rotation behavior, we limited maximum number of rotation in recent unbonding period and also applied exponentially increasing rotation fee
* limits
* a validator cannot rotate its consensus key more than `MaxConsPubKeyRotations` time for any unbonding period, to prevent spam.
* rotations are limited to 1 time in an unbonding window. In future rewrites of the staking module it could be made to happen more times than 1
* parameters can be decided by governance and stored in genesis file.
* key rotation fee
* a validator should pay `KeyRotationFee` to rotate the consensus key which is calculated as below
* `KeyRotationFee` = (max(`VotingPowerPercentage` *100, 1)* `InitialKeyRotationFee`) * 2^(number of rotations in `ConsPubKeyRotationHistory` in recent unbonding period)
* `KeyRotationFee` = (max(`VotingPowerPercentage`, 1)* `InitialKeyRotationFee`) * 2^(number of rotations in `ConsPubKeyRotationHistory` in recent unbonding period)
* evidence module
* evidence module can search corresponding consensus key for any height from slashing keeper so that it can decide which consensus key is supposed to be used for given height.
* abci.ValidatorUpdate
Expand Down Expand Up @@ -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 (https://nearprotocol.com/blog/long-range-attacks-and-a-new-fork-choice-rule) given a validator throws away the old consensus key(s)
* improved security against Long-Range attacks (https://near.org/blog/long-range-attacks-and-a-new-fork-choice-rule) given a validator throws away the old consensus key(s)

### Negative

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
* 2021 Feb 24: The Cosmos SDK does not use Tendermint's `PubKey` interface anymore, but its own `cryptotypes.PubKey`. Updates to reflect this.
* 2021 May 3: Rename `clientCtx.JSONMarshaler` to `clientCtx.JSONCodec`.
* 2021 June 10: Add `clientCtx.Codec: codec.Codec`.
* 2024 February 5: Account creation step

## Status

Expand Down Expand Up @@ -317,6 +318,8 @@ the client logic will now need to take a codec interface that knows not only how
to handle all the types, but also knows how to generate transactions, signatures,
and messages.

If the account is sending its first transaction, the account number must be set to 0. This is due to the account not being created yet.

```go
type AccountRetriever interface {
GetAccount(clientCtx Context, addr sdk.AccAddress) (client.Account, error)
Expand Down Expand Up @@ -346,7 +349,7 @@ type TxBuilder interface {
```

We then update `Context` to have new fields: `Codec`, `TxGenerator`,
and `AccountRetriever`, and we update `AppModuleBasic.GetTxCmd` to take
and `AccountRetriever`, and we update `AppModule.GetTxCmd` to take
a `Context` which should have all of these fields pre-populated.

Each client method should then use one of the `Init` methods to re-initialize
Expand Down
2 changes: 1 addition & 1 deletion docs/build/architecture/adr-022-custom-panic-handling.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ We propose middleware-solution, which could help developers implement the follow
* call panic for specific error cases;

It will also make `OutOfGas` case and `default` case one of the middlewares.
`Default` case wraps recovery object to an error and logs it ([example middleware implementation](#Recovery-middleware)).
`Default` case wraps recovery object to an error and logs it ([example middleware implementation](#recovery-middleware)).

Our project has a sidecar service running alongside the blockchain node (smart contracts virtual machine). It is
essential that node <-> sidecar connectivity stays stable for TXs processing. So when the communication breaks we need
Expand Down
1 change: 0 additions & 1 deletion docs/build/architecture/adr-031-msg-service.md
Original file line number Diff line number Diff line change
Expand Up @@ -197,6 +197,5 @@ Finally, closing a module to client API opens desirable OCAP patterns discussed

* [Initial Github Issue \#7122](https://github.com/cosmos/cosmos-sdk/issues/7122)
* [proto 3 Language Guide: Defining Services](https://developers.google.com/protocol-buffers/docs/proto3#services)
* [Initial pre-`Any` `Msg` designs](https://docs.google.com/document/d/1eEgYgvgZqLE45vETjhwIw4VOqK-5hwQtZtjVbiXnIGc)
* [ADR 020](./adr-020-protobuf-transaction-encoding.md)
* [ADR 021](./adr-021-protobuf-query-encoding.md)
6 changes: 3 additions & 3 deletions docs/build/architecture/adr-032-typed-events.md
Original file line number Diff line number Diff line change
Expand Up @@ -261,7 +261,7 @@ func TxEmitter(ctx context.Context, cliCtx client.Context, ehs ...EventHandler)
}

// PublishChainTxEvents events using cmtclient. Waits on context shutdown signals to exit.
func PublishChainTxEvents(ctx context.Context, client cmtclient.EventsClient, bus pubsub.Bus, mb module.BasicManager) (err error) {
func PublishChainTxEvents(ctx context.Context, client cmtclient.EventsClient, bus pubsub.Bus) (err error) {
// Subscribe to transaction events
txch, err := client.Subscribe(ctx, "txevents", "tm.event='Tx'", 100)
if err != nil {
Expand Down Expand Up @@ -289,12 +289,12 @@ func PublishChainTxEvents(ctx context.Context, client cmtclient.EventsClient, bu
if !evt.Result.IsOK() {
continue
}
// range over events, parse them using the basic manager and
// range over events and parse them
// send them to the pubsub bus
for _, abciEv := range events {
typedEvent, err := sdk.ParseTypedEvent(abciEv)
if err != nil {
return er
return err
}
if err := bus.Publish(typedEvent); err != nil {
bus.Close()
Expand Down
8 changes: 4 additions & 4 deletions docs/build/architecture/adr-033-protobuf-inter-module-comm.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ service definitions defined in [ADR 021](./adr-021-protobuf-query-encoding.md) a

## Context

In the current Cosmos SDK documentation on the [Object-Capability Model](../../learn/advanced/10-ocap.md), it is stated that:
In the current Cosmos SDK documentation on the [Object-Capability Model](https://docs.cosmos.network/main/learn/advanced/ocap#ocaps-in-practice), it is stated that:

> We assume that a thriving ecosystem of Cosmos SDK modules that are easy to compose into a blockchain application will contain faulty or malicious modules.
Expand Down Expand Up @@ -264,7 +264,7 @@ type Configurator interface {

The `ModuleKey` is passed to modules in the `RegisterService` method itself so that `RegisterServices` serves as a single
entry point for configuring module services. This is intended to also have the side-effect of greatly reducing boilerplate in
`app.go`. For now, `ModuleKey`s will be created based on `AppModuleBasic.Name()`, but a more flexible system may be
`app.go`. For now, `ModuleKey`s will be created based on `AppModule.Name()`, but a more flexible system may be
introduced in the future. The `ModuleManager` will handle creation of module accounts behind the scenes.

Because modules do not get direct access to each other anymore, modules may have unfulfilled dependencies. To make sure
Expand Down Expand Up @@ -344,7 +344,7 @@ Other future improvements may include:
* optimizes inter-module calls - for instance caching resolved methods after first invocation
* combining `StoreKey`s and `ModuleKey`s into a single interface so that modules have a single OCAPs handle
* code generation which makes inter-module communication more performant
* decoupling `ModuleKey` creation from `AppModuleBasic.Name()` so that app's can override root module account names
* decoupling `ModuleKey` creation from `AppModule.Name()` so that app's can override root module account names
* inter-module hooks and plugins

## Alternatives
Expand Down Expand Up @@ -397,4 +397,4 @@ replacing `Keeper` interfaces altogether.
* [ADR 031](./adr-031-msg-service.md)
* [ADR 028](./adr-028-public-key-addresses.md)
* [ADR 030 draft](https://github.com/cosmos/cosmos-sdk/pull/7105)
* [Object-Capability Model](https://docs.network.com/main/core/ocap)
* [Object-Capability Model](https://docs.cosmos.network/main/learn/advanced/ocap#ocaps-in-practice)
4 changes: 2 additions & 2 deletions docs/build/architecture/adr-034-account-rekeying.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,5 +72,5 @@ Breaks the current assumed relationship between address and pubkeys as H(pubkey)
* Will require that PubKeys for an account are included in the genesis exports.

## References

* https://algorand.com/resources/algorand-announcements/announcing-rekeying
<!-- markdown-link-check-disable-next-line -->
* https://algorandtechnologies.com/news/announcing-rekeying
2 changes: 1 addition & 1 deletion docs/build/architecture/adr-038-state-listening.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ This ADR defines a set of changes to enable listening to state changes of indivi

## Context

Currently, KVStore data can be remotely accessed through [Queries](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules/messages-and-queries.md#queries)
Currently, KVStore data can be remotely accessed through [Queries](https://github.com/cosmos/cosmos-sdk/blob/main/docs/build/building-modules/02-messages-and-queries.md#queries)
which proceed either through Tendermint and the ABCI, or through the gRPC server.
In addition to these request/response queries, it would be beneficial to have a means of listening to state changes as they occur in real time.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -285,5 +285,5 @@ We were discussing use case where modules can use a support database, which is n
* Facebook Diem (Libra) SMT [design](https://developers.diem.com/papers/jellyfish-merkle-tree/2021-01-14.pdf)
* [Trillian Revocation Transparency](https://github.com/google/trillian/blob/master/docs/papers/RevocationTransparency.pdf), [Trillian Verifiable Data Structures](https://github.com/google/trillian/blob/master/docs/papers/VerifiableDataStructures.pdf).
* Design and implementation [discussion](https://github.com/cosmos/cosmos-sdk/discussions/8297).
* [How to Upgrade IBC Chains and their Clients](https://github.com/cosmos/ibc-go/blob/main/docs/ibc/upgrades/quick-guide.md)
* [How to Upgrade IBC Chains and their Clients](https://github.com/cosmos/ibc-go/blob/main/docs/docs/01-ibc/05-upgrades/01-quick-guide.md)
* [ADR-40 Effect on IBC](https://github.com/cosmos/ibc-go/discussions/256)
Loading

0 comments on commit cdf5b49

Please sign in to comment.