Skip to content

Commit

Permalink
chore: Sync docs from cosmos-sdk/docs
Browse files Browse the repository at this point in the history
  • Loading branch information
tac0turtle authored and github-actions[bot] committed Apr 23, 2024
1 parent cdf5b49 commit c90bbf6
Show file tree
Hide file tree
Showing 33 changed files with 225 additions and 179 deletions.
4 changes: 2 additions & 2 deletions docs/build/abci/00-introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## What is ABCI?

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.
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/v1.0/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 (compared to ABCI v0) are:

Expand Down Expand Up @@ -41,7 +41,7 @@ If vote extensions are enabled, `ExtendVote` will be called on every validator a

`VerifyVoteExtensions` is performed on every validator multiple times in order to verify other validators' vote extensions. This check is submitted to validate the integrity and validity of the vote extensions preventing malicious or invalid vote extensions.

Additionally, applications must keep the vote extension data concise as it can degrade the performance of their chain, see testing results [here](https://docs.cometbft.com/v0.38/qa/cometbft-qa-38#vote-extensions-testbed).
Additionally, applications must keep the vote extension data concise as it can degrade the performance of their chain, see testing results [here](https://docs.cometbft.com/v1.0/references/qa/cometbft-qa-38#vote-extensions-testbed).

`VerifyVoteExtensions` MUST be deterministic.

Expand Down
12 changes: 6 additions & 6 deletions docs/build/abci/03-vote-extensions.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,21 +11,21 @@ ABCI2.0 (colloquially called ABCI++) allows an application to extend a pre-commi
validator process. The Cosmos SDK defines [`baseapp.ExtendVoteHandler`](https://github.com/cosmos/cosmos-sdk/blob/v0.50.1/types/abci.go#L26-L27):

```go
type ExtendVoteHandler func(Context, *abci.RequestExtendVote) (*abci.ResponseExtendVote, error)
type ExtendVoteHandler func(Context, *abci.ExtendVoteRequest) (*abci.ExtendVoteResponse, error)
```

An application can set this handler in `app.go` via the `baseapp.SetExtendVoteHandler`
`BaseApp` option function. The `sdk.ExtendVoteHandler`, if defined, is called during
the `ExtendVote` ABCI method. Note, if an application decides to implement
`baseapp.ExtendVoteHandler`, it MUST return a non-nil `VoteExtension`. However, the vote
extension can be empty. See [here](https://github.com/cometbft/cometbft/blob/v0.38.0-rc1/spec/abci/abci++_methods.md#extendvote)
extension can be empty. See [here](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#extendvote)
for more details.

There are many decentralized censorship-resistant use cases for vote extensions.
For example, a validator may want to submit prices for a price oracle or encryption
shares for an encrypted transaction mempool. Note, an application should be careful
to consider the size of the vote extensions as they could increase latency in block
production. See [here](https://github.com/cometbft/cometbft/blob/v0.38.0-rc1/docs/qa/CometBFT-QA-38.md#vote-extensions-testbed)
production. See [here](https://docs.cometbft.com/v1.0/references/qa/cometbft-qa-38#vote-extensions-testbed)
for more details.

Click [here](https://docs.cosmos.network/main/build/abci/vote-extensions) if you would like a walkthrough of how to implement vote extensions.
Expand All @@ -38,18 +38,18 @@ other validators when validating their pre-commits. For a given vote extension,
this process MUST be deterministic. The Cosmos SDK defines [`sdk.VerifyVoteExtensionHandler`](https://github.com/cosmos/cosmos-sdk/blob/v0.50.1/types/abci.go#L29-L31):

```go
type VerifyVoteExtensionHandler func(Context, *abci.RequestVerifyVoteExtension) (*abci.ResponseVerifyVoteExtension, error)
type VerifyVoteExtensionHandler func(Context, *abci.VerifyVoteExtensionRequest) (*abci.VerifyVoteExtensionResponse, error)
```

An application can set this handler in `app.go` via the `baseapp.SetVerifyVoteExtensionHandler`
`BaseApp` option function. The `sdk.VerifyVoteExtensionHandler`, if defined, is called
during the `VerifyVoteExtension` ABCI method. If an application defines a vote
extension handler, it should also define a verification handler. Note, not all
validators will share the same view of what vote extensions they verify depending
on how votes are propagated. See [here](https://github.com/cometbft/cometbft/blob/v0.38.0-rc1/spec/abci/abci++_methods.md#verifyvoteextension)
on how votes are propagated. See [here](https://docs.cometbft.com/v1.0/spec/abci/abci++_methods#verifyvoteextension)
for more details.

Additionally, please keep in mind that performance can be degraded if vote extensions are too big (https://docs.cometbft.com/v0.38/qa/cometbft-qa-38#vote-extensions-testbed), so we highly recommend a size validation in `VerifyVoteExtensions`.
Additionally, please keep in mind that performance can be degraded if vote extensions are too big ([see vote extension testbed](https://docs.cometbft.com/v1.0/references/qa/cometbft-qa-38#vote-extensions-testbed)), so we highly recommend a size validation in `VerifyVoteExtensions`.


## Vote Extension Propagation
Expand Down
2 changes: 1 addition & 1 deletion docs/build/architecture/adr-062-collections-state-layer.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ These default implementations also offer safety around proper lexicographic orde

Examples of the collections API can be found here:
- introduction: https://github.com/NibiruChain/collections/tree/main/examples
- usage in nibiru: [x/oracle](https://github.com/NibiruChain/nibiru/blob/master/x/oracle/keeper/keeper.go#L32), [x/perp](https://github.com/NibiruChain/nibiru/blob/main/x/perp/v2/keeper/keeper.go)
- usage in nibiru: [x/oracle](https://github.com/NibiruChain/nibiru/blob/master/x/oracle/keeper/keeper.go#L32), [x/epoch](https://github.com/NibiruChain/nibiru/blob/4566d9f6d22807abbd78c01454664d64f6e108e0/x/epochs/keeper/epoch.go)
- cosmos-sdk's x/staking migrated: https://github.com/testinginprod/cosmos-sdk/pull/22


Expand Down
3 changes: 2 additions & 1 deletion docs/build/architecture/adr-063-core-module-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -330,7 +330,7 @@ Header Service defines a way to get header information about a block. This infor
```go

type Service interface {
GetHeaderInfo(context.Context) Info
HeaderInfo(context.Context) Info
}

type Info struct {
Expand Down Expand Up @@ -463,6 +463,7 @@ module manager and follow the Cosmos SDK's existing [0-based versioning](https:/
versioning as well as runtime modularity, new officially supported runtime modules will be created under the
`cosmossdk.io/runtime` prefix. For each supported consensus engine a semantically-versioned go module should be created
with a runtime implementation for that consensus engine. For example:

* `cosmossdk.io/runtime/comet`
* `cosmossdk.io/runtime/comet/v2`
* `cosmossdk.io/runtime/rollkit`
Expand Down
2 changes: 1 addition & 1 deletion docs/build/architecture/adr-064-abci-2.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -401,7 +401,7 @@ in both `BeginBlock` and `EndBlock` events`.

### Upgrading

CometBFT defines a consensus parameter, [`VoteExtensionsEnableHeight`](https://github.com/cometbft/cometbft/blob/v0.38.0-alpha.1/spec/abci/abci%2B%2B_app_requirements.md#abciparamsvoteextensionsenableheight),
CometBFT defines a consensus parameter, [`VoteExtensionsEnableHeight`](https://docs.cometbft.com/v1.0/spec/abci/abci++_app_requirements#featureparamsvoteextensionsenableheight),
which specifies the height at which vote extensions are enabled and **required**.
If the value is set to zero, which is the default, then vote extensions are
disabled and an application is not required to implement and use vote extensions.
Expand Down
2 changes: 1 addition & 1 deletion docs/build/building-apps/02-app-mempool.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ This sections describes how the app-side mempool can be used and replaced.

Since `v0.47` the application has its own mempool to allow much more granular
block building than previous versions. This change was enabled by
[ABCI 1.0](https://github.com/cometbft/cometbft/blob/v0.37.0/spec/abci).
[ABCI 1.0](https://docs.cometbft.com/v0.37/spec/abci/).
Notably it introduces the `PrepareProposal` and `ProcessProposal` steps of ABCI++. For more information please see [here](../abci/00-introduction.md)

:::note Pre-requisite Readings
Expand Down
Loading

0 comments on commit c90bbf6

Please sign in to comment.