Merge branch 'v1.x' into mergify/bp/v1.x/pr-2394

app/ante/ante.go

@@ -21,24 +21,48 @@ func NewAnteHandler(
 	channelKeeper *ibckeeper.Keeper,
 ) sdk.AnteHandler {
 	return sdk.ChainAnteDecorators(
-		ante.NewSetUpContextDecorator(), // outermost AnteDecorator. SetUpContext must be called first
-		// reject all tx extensions
+		// Set up the context with a gas meter.
+		// Contract: must be called first.
+		ante.NewSetUpContextDecorator(),
+		// Ensure the tx does not contain any extension options.
 		ante.NewExtensionOptionsDecorator(nil),
+		// Ensure the tx passes ValidateBasic.
 		ante.NewValidateBasicDecorator(),
+		// Ensure the tx has not reached a height timeout.
 		ante.NewTxTimeoutHeightDecorator(),
+		// Ensure the tx memo <= max memo characters.
 		ante.NewValidateMemoDecorator(accountKeeper),
+		// Ensure the tx's gas limit is > the gas consumed based on the tx size.
+		// Side effect: consumes gas from the gas meter.
 		ante.NewConsumeGasForTxSizeDecorator(accountKeeper),
-		// check that the fee matches the gas and the local minimum gas price
-		// of the validator
+		// Ensure the feepayer (fee granter or first signer) has enough funds to pay for the tx.
+		// Side effect: deducts fees from the fee payer. Sets the tx priority in context.
 		ante.NewDeductFeeDecorator(accountKeeper, bankKeeper, feegrantKeeper, checkTxFeeWithValidatorMinGasPrices),
-		ante.NewSetPubKeyDecorator(accountKeeper), // SetPubKeyDecorator must be called before all signature verification decorators
+		// Set public keys in the context for fee-payer and all signers.
+		// Contract: must be called before all signature verification decorators.
+		ante.NewSetPubKeyDecorator(accountKeeper),
+		// Ensure that the tx's count of signatures is <= the tx signature limit.
 		ante.NewValidateSigCountDecorator(accountKeeper),
+		// Ensure that the tx's gas limit is > the gas consumed based on signature verification.
+		// Side effect: consumes gas from the gas meter.
 		ante.NewSigGasConsumeDecorator(accountKeeper, sigGasConsumer),
+		// Ensure that the tx's signatures are valid. For each signature, ensure
+		// that the signature's sequence number (a.k.a nonce) matches the
+		// account sequence number of the signer.
+		// Note: does not consume gas from the gas meter.
 		ante.NewSigVerificationDecorator(accountKeeper, signModeHandler),
+		// Ensure that the tx's gas limit is > the gas consumed based on the blob size(s).
+		// Contract: must be called after all decorators that consume gas.
+		// Note: does not consume gas from the gas meter.
 		blobante.NewMinGasPFBDecorator(blobKeeper),
+		// Ensure that the tx's total blob size is <= the max blob size.
 		blobante.NewMaxBlobSizeDecorator(blobKeeper),
+		// Ensure that tx's with a MsgSubmitProposal have atleast one proposal
+		// message.
 		NewGovProposalDecorator(),
+		// Side effect: increment the nonce for all tx signers.
 		ante.NewIncrementSequenceDecorator(accountKeeper),
+		// Ensure that the tx is not a IBC packet or update message that has already been processed.
 		ibcante.NewRedundantRelayDecorator(channelKeeper),
 	)
 }

app/ante/fee_checker.go

@@ -12,7 +12,7 @@ const (
 )
 
 // checkTxFeeWithValidatorMinGasPrices implements the default fee logic, where the minimum price per
-// unit of gas is fixed and set by each validator, can the tx priority is computed from the gas price.
+// unit of gas is fixed and set by each validator, and the tx priority is computed from the gas price.
 func checkTxFeeWithValidatorMinGasPrices(ctx sdk.Context, tx sdk.Tx) (sdk.Coins, int64, error) {
 	feeTx, ok := tx.(sdk.FeeTx)
 	if !ok {

app/ante/gov.go

@@ -7,6 +7,8 @@ import (
 	govv1 "github.com/cosmos/cosmos-sdk/x/gov/types/v1"
 )
 
+// GovProposalDecorator ensures that a tx with a MsgSubmitProposal has at least
+// one message in the proposal.
 type GovProposalDecorator struct{}
 
 func NewGovProposalDecorator() GovProposalDecorator {

app/check_tx.go

@@ -18,6 +18,7 @@ func (app *App) CheckTx(req abci.RequestCheckTx) abci.ResponseCheckTx {
 	btx, isBlob := coretypes.UnmarshalBlobTx(tx)
 
 	if !isBlob {
+		// reject transactions that can't be decoded
 		sdkTx, err := app.txConfig.TxDecoder()(tx)
 		if err != nil {
 			return sdkerrors.ResponseCheckTxWithEvents(err, 0, 0, []abci.Event{}, false)

app/test/std_sdk_test.go

@@ -3,6 +3,7 @@ package app_test
 import (
 	"sync"
 	"testing"
+	"time"
 
 	"github.com/celestiaorg/celestia-app/app"
 	"github.com/celestiaorg/celestia-app/app/encoding"
@@ -144,7 +145,7 @@ func (s *StandardSDKIntegrationTestSuite) TestStandardSDK() {
 			expectedCode: abci.CodeTypeOK,
 		},
 		{
-			name: "create vesting account",
+			name: "create continuous vesting account with a start time in the future",
 			msgFunc: func() (msgs []sdk.Msg, signer string) {
 				vestAccName := "vesting"
 				_, _, err := s.cctx.Keyring.NewMnemonic(vestAccName, keyring.English, "", "", hd.Secp256k1)
@@ -156,7 +157,9 @@ func (s *StandardSDKIntegrationTestSuite) TestStandardSDK() {
 					sendingAccAddr,
 					vestAccAddr,
 					sdk.NewCoins(sdk.NewCoin(app.BondDenom, sdk.NewInt(1000000))),
-					10000, true,
+					time.Now().Add(time.Hour).Unix(),
+					time.Now().Add(time.Hour*2).Unix(),
+					false,
 				)
 				return []sdk.Msg{msg}, sendAcc
 			},

go.mod

@@ -214,7 +214,7 @@ require (
 )
 
 replace (
-	github.com/cosmos/cosmos-sdk => github.com/celestiaorg/cosmos-sdk v1.17.0-sdk-v0.46.14
+	github.com/cosmos/cosmos-sdk => github.com/celestiaorg/cosmos-sdk v1.18.0-sdk-v0.46.14
 	github.com/gogo/protobuf => github.com/regen-network/protobuf v1.3.3-alpha.regen.1
 	github.com/syndtr/goleveldb => github.com/syndtr/goleveldb v1.0.1-0.20210819022825-2ae1ddf74ef7
 	github.com/tendermint/tendermint => github.com/celestiaorg/celestia-core v1.26.2-tm-v0.34.28

go.sum

@@ -179,8 +179,8 @@ github.com/c-bata/go-prompt v0.2.2/go.mod h1:VzqtzE2ksDBcdln8G7mk2RX9QyGjH+OVqOC
 github.com/casbin/casbin/v2 v2.1.2/go.mod h1:YcPU1XXisHhLzuxH9coDNf2FbKpjGlbCg3n9yuLkIJQ=
 github.com/celestiaorg/celestia-core v1.26.2-tm-v0.34.28 h1:2efXQaggLFknz0wQufr4nUEz5G7pSVHS1j7NuJDsvII=
 github.com/celestiaorg/celestia-core v1.26.2-tm-v0.34.28/go.mod h1:++dNzzzjP9jYg+NopN9G8sg1HEZ58lv1TPtg71evZ0E=
-github.com/celestiaorg/cosmos-sdk v1.17.0-sdk-v0.46.14 h1:PckXGxLJjXv97VO3xS8NPHN5oO83X5nvJLbc/4s8jUM=
-github.com/celestiaorg/cosmos-sdk v1.17.0-sdk-v0.46.14/go.mod h1:70Go8qNy7YAb1PUcHCChRHNX2ke7c9jgUIEklUX+Mac=
+github.com/celestiaorg/cosmos-sdk v1.18.0-sdk-v0.46.14 h1:dDfoQJOlVNj4HufJ1lBLTo2k3/L/255MIiKmEQziDmw=
+github.com/celestiaorg/cosmos-sdk v1.18.0-sdk-v0.46.14/go.mod h1:kkdiHo/zG6ar80730+bG1owdMAQXrGp4utFu7mbfADo=
 github.com/celestiaorg/merkletree v0.0.0-20210714075610-a84dc3ddbbe4 h1:CJdIpo8n5MFP2MwK0gSRcOVlDlFdQJO1p+FqdxYzmvc=
 github.com/celestiaorg/merkletree v0.0.0-20210714075610-a84dc3ddbbe4/go.mod h1:fzuHnhzj1pUygGz+1ZkB3uQbEUL4htqCGJ4Qs2LwMZA=
 github.com/celestiaorg/nmt v0.19.0 h1:9VXFeI/gt+q8h5HeCE0RjXJhOxsFzxJUjHrkvF9CMYE=

specs/src/README.md

@@ -7,6 +7,8 @@
   - [Consensus](./specs/consensus.md)
   - [Block Proposer](./specs/block_proposer.md)
   - [Block Validity Rules](./specs/block_validity_rules.md)
+  - [AnteHandler](./specs/ante_handler.md)
+  - [Fraud Proofs](./specs/fraud_proofs.md)
   - [Networking](./specs/networking.md)
   - [Public-Key Cryptography](./specs/public_key_cryptography.md)
   - [Data Square Layout](./specs/data_square_layout.md)

specs/src/SUMMARY.md

@@ -9,6 +9,8 @@
   - [Consensus](./specs/consensus.md)
   - [Block Proposer](./specs/block_proposer.md)
   - [Block Validity Rules](./specs/block_validity_rules.md)
+  - [AnteHandler](./specs/ante_handler.md)
+  - [Fraud Proofs](./specs/fraud_proofs.md)
   - [Networking](./specs/networking.md)
   - [Public-Key Cryptography](./specs/public_key_cryptography.md)
   - [Data Square Layout](./specs/data_square_layout.md)

specs/src/specs/ante_handler.md

@@ -0,0 +1,30 @@
+# AnteHandler
+
+Celestia makes use of a Cosmos SDK [AnteHandler](https://docs.cosmos.network/v0.46/modules/auth/03_antehandlers.html#antehandlers) in order to reject decodable sdk.Txs that do not meet certain criteria. The AnteHandler is defined in [app/ante/ante.go](https://github.com/celestiaorg/celestia-app/blob/7f97788a64af7fe0fce00959753d6dd81663e98f/app/ante/ante.go) and is invoked at multiple times during the transaction lifecycle:
+
+1. `CheckTx` prior to the transaction entering the mempool
+1. `PrepareProposal` when the block proposer includes the transaction in a block proposal
+1. `ProcessProposal` when validators validate the transaction in a block proposal
+1. `DeliverTx` when full nodes execute the transaction in a decided block
+
+The AnteHandler chains together several decorators to ensure the following criteria are met:
+
+- The tx does not contain any [extension options](https://github.com/cosmos/cosmos-sdk/blob/22c28366466e64ebf0df1ce5bec8b1130523552c/proto/cosmos/tx/v1beta1/tx.proto#L119-L122).
+- The tx passes `ValidateBasic()`.
+- The tx's [timeout_height](https://github.com/cosmos/cosmos-sdk/blob/22c28366466e64ebf0df1ce5bec8b1130523552c/proto/cosmos/tx/v1beta1/tx.proto#L115-L117) has not been reached if one is specified.
+- The tx's [memo](https://github.com/cosmos/cosmos-sdk/blob/22c28366466e64ebf0df1ce5bec8b1130523552c/proto/cosmos/tx/v1beta1/tx.proto#L110-L113) is <= the max memo characters where [`MaxMemoCharacters = 256`](<https://github.com/cosmos/cosmos-sdk/blob/a429238fc267da88a8548bfebe0ba7fb28b82a13/x/auth/README.md?plain=1#L230>).
+- The tx's [gas_limit](https://github.com/cosmos/cosmos-sdk/blob/22c28366466e64ebf0df1ce5bec8b1130523552c/proto/cosmos/tx/v1beta1/tx.proto#L211-L213) is > the gas consumed based on the tx's size where [`TxSizeCostPerByte = 10`](https://github.com/cosmos/cosmos-sdk/blob/a429238fc267da88a8548bfebe0ba7fb28b82a13/x/auth/README.md?plain=1#L232).
+- The tx's feepayer has enough funds to pay fees for the tx. The tx's feepayer is the feegranter (if specified) or the tx's first signer. Note the [feegrant](https://docs.cosmos.network/v0.46/) module is enabled.
+- The tx's count of signatures <= the max number of signatures. The max number of signatures is [`TxSigLimit = 7`](https://github.com/cosmos/cosmos-sdk/blob/a429238fc267da88a8548bfebe0ba7fb28b82a13/x/auth/README.md?plain=1#L231).
+- The tx's [gas_limit](https://github.com/cosmos/cosmos-sdk/blob/22c28366466e64ebf0df1ce5bec8b1130523552c/proto/cosmos/tx/v1beta1/tx.proto#L211-L213) is > the gas consumed based on the tx's signatures.
+- The tx's [signatures](https://github.com/cosmos/cosmos-sdk/blob/22c28366466e64ebf0df1ce5bec8b1130523552c/types/tx/signing/signature.go#L10-L26) are valid. For each signature, ensure that the signature's sequence number (a.k.a nonce) matches the account sequence number of the signer.
+- The tx's [gas_limit](https://github.com/cosmos/cosmos-sdk/blob/22c28366466e64ebf0df1ce5bec8b1130523552c/proto/cosmos/tx/v1beta1/tx.proto#L211-L213) is > the gas consumed based on the blob size(s). Since blobs are charged based on the number of shares they occupy, the gas consumed is calculated as follows: `gasToConsume = sharesNeeded(blob) * bytesPerShare * gasPerBlobByte`. Where `bytesPerShare` is a a global constant (an alias for [`ShareSize = 512`](https://github.com/celestiaorg/celestia-app/blob/c90e61d5a2d0c0bd0e123df4ab416f6f0d141b7f/pkg/appconsts/global_consts.go#L27-L28)) and `gasPerBlobByte` is a governance parameter that can be modified (the [`DefaultGasPerBlobByte = 8`](https://github.com/celestiaorg/celestia-app/blob/c90e61d5a2d0c0bd0e123df4ab416f6f0d141b7f/pkg/appconsts/initial_consts.go#L16-L18)).
+- The tx's total blob size is <= the max blob size. The max blob size is derived from the maximum valid square size. The max valid square size is the minimum of: `GovMaxSquareSize` and `SquareSizeUpperBound`.
+- The tx does not contain a message of type [MsgSubmitProposal](https://github.com/cosmos/cosmos-sdk/blob/d6d929843bbd331b885467475bcb3050788e30ca/proto/cosmos/gov/v1/tx.proto#L33-L43) with zero proposal messages.
+- The tx is not an IBC packet or update message that has already been processed.
+
+In addition to the above criteria, the AnteHandler also has a number of side-effects:
+
+- Tx fees are deducted from the tx's feepayer and added to the fee collector module account.
+- Tx priority is calculated based on the the smallest denomination of gas price in the tx and set in context.
+- The nonce of all tx signers is incremented by 1.

specs/src/specs/block_validity_rules.md

@@ -1 +1,53 @@
 # Block Validity Rules
+
+## Introduction
+
+Unlike most blockchains, Celestia derives most of its functionality from
+stateless commitments to data rather than stateful transitions. This means that
+the protocol relies heavily on block validity rules. Notably, resource
+constrained light clients must be able to detect when a subset of these validity
+rules have not been followed in order to avoid making an honest majority
+assumption on the consensus network. This has a significant impact on thier
+design. More information on how light clients can check the invalidity of a
+block can be foud in the [Fraud Proofs](./fraud_proofs.md) spec.
+
+> **Note** Celestia relies on CometBFT (formerly tendermint) for consensus,
+> meaning that it has single slot finality and is fork-free. Therefore, in order
+> to ensure that an invalid block is never committed to, each validator must
+> check that each block follows all validity rules before voting. If over two
+> thirds of the voting power colludes to break a validity rule, then fraud
+> proofs are created for light clients. After light clients verify fraud proofs,
+> they halt.
+
+## Validity Rules
+
+Before any Celestia specific validation is performed, all CometBFT [block
+validation
+rules](https://github.com/cometbft/cometbft/blob/v0.34.28/spec/core/data_structures.md#block)
+must be followed.
+
+Notably, this includes verifying data availability. Consensus nodes verify data
+availabily by simply downloading the entire block.
+
+> **Note** Light clients only sample a fraction of the block. More details on
+> how sampling actually works can be found in the seminal ["Fraud and Data
+> Availability Proofs: Maximising Light Client Security and Scaling Blockchains
+> with Dishonest Majorities"](https://arxiv.org/abs/1809.09044) and in the
+> [`celestia-node`](https://github.com/celestiaorg/celestia-node) repo.
+
+Celestia specifc validity rules can be categorized into two groups:
+
+### Transaction Validity Rules
+
+All `BlobTx` transactions must be valid according to the [BlobTx validity rules](../../../x/blob/README.md#validity-rules).
+
+All remaining transactions must be decodable and pass all [AnteHandler](./ante_handler.md) checks.
+
+For a complete list of modules see [state machine modules](./state_machine_modules.md).
+
+### Data Root Construction
+
+The data root must be calculated from a correctly constructed data square per the [data square layout rules](./data_square_layout.md)
+
+<img src="./figures/rs2d_extending.svg" alt="Figure 1: Erasure Encoding" width="400"/> <img
+src="./figures/rs2d_quadrants.svg" alt="Figure 2: rsmt2d" width="400"/> <img src="./figures/data_root.svg" alt="Figure 3: Data Root" width="400"/>

specs/src/specs/data_square_layout.md

@@ -4,7 +4,7 @@
 
 ## Preamble
 
-Celestia uses [a data availability scheme](https://arxiv.org/abs/1809.09044) that allows nodes to determine whether a block's data was published without downloading the whole block. The core of this scheme is arranging data in a two-dimensional matrix then applying erasure coding to each row and column. This document describes the rationale for how data—transactions, blobs, and other data—[is actually arranged](./data_structures.md#arranging-available-data-into-shares). Familiarity with the [originally proposed data layout format](https://arxiv.org/abs/1809.09044) is assumed.
+Celestia uses [a data availability scheme](https://arxiv.org/abs/1809.09044) that allows nodes to determine whether a block's data was published without downloading the whole block. The core of this scheme is arranging data in a two-dimensional matrix of [shares](./shares.md), then applying erasure coding to each row and column. This document describes the rationale for how data—transactions, blobs, and other data—[is actually arranged](./data_structures.md#arranging-available-data-into-shares). Familiarity with the [originally proposed data layout format](https://arxiv.org/abs/1809.09044) is assumed.
 
 ## Layout Rationale
 

specs/src/specs/fraud_proofs.md

@@ -0,0 +1,25 @@
+# Fraud Proofs
+
+## Bad Encoding Fraud Proofs
+
+In order for data availability sampling to work, light clients must be convinced
+that erasure encoded parity data was encoded correctly. For light clients, this
+is ultimately enforced via [bad encoding fraud proofs
+(BEFPs)](https://github.com/celestiaorg/celestia-node/blob/v0.11.0-rc3/docs/adr/adr-006-fraud-service.md#detailed-design).
+Consensus nodes must verify this themselves before considering a block valid.
+This is done automatically by verifying the data root of the header, since that
+requires reconstructing the square from the block data, performing the erasure
+encoding, calculating the data root using that representation, and then
+comparing the data root found in the header.
+
+## Blob Inclusion
+
+TODO
+
+## State
+
+State fraud proofs allow light clients to avoid making an honest majority assumption for
+state validity. While these are not incorporated into the protocol as of v1.0.0,
+there are example implementations that can be found in
+[Rollkit](https://github.com/rollkit/rollkit). More info in
+[rollkit-ADR009](https://github.com/rollkit/rollkit/blob/4fd97ba8b8352771f2e66454099785d06fd0c31b/docs/lazy-adr/adr-009-state-fraud-proofs.md).