docs(specs): remove root level specification page (#3822)

Closes #3751

specs/src/SUMMARY.md

@@ -2,26 +2,25 @@
 
 Celestia App Specifications
 
-- [Specification](./specs/index.md)
-  - [Data Structures](./specs/data_structures.md)
-  - [Namespace](./specs/namespace.md)
-  - [Shares](./specs/shares.md)
-  - [Consensus](./specs/consensus.md)
-    - [CAT Pool](./specs/cat_pool.md)
-  - [Block Proposer](./specs/block_proposer.md)
-  - [Block Validity Rules](./specs/block_validity_rules.md)
-  - [AnteHandler](./specs/ante_handler.md)
-    - [AnteHandler v1](./specs/ante_handler_v1.md)
-    - [AnteHandler v2](./specs/ante_handler_v2.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)
-  - [Resource Pricing](./specs/resource_pricing.md)
-  - [Multisig](./specs/multisig.md)
-- [State Machine Modules](./specs/state_machine_modules.md)
-  - [State Machine Modules v1](./specs/state_machine_modules_v1.md)
-  - [State Machine Modules v2](./specs/state_machine_modules_v2.md)
-- [Parameters](./specs/parameters.md)
-  - [Parameters v1](./specs/parameters_v1.md)
-  - [Parameters v2](./specs/parameters_v2.md)
+- [Data Structures](./data_structures.md)
+- [Namespace](./namespace.md)
+- [Shares](./shares.md)
+- [Consensus](./consensus.md)
+  - [CAT Pool](./cat_pool.md)
+- [Block Proposer](./block_proposer.md)
+- [Block Validity Rules](./block_validity_rules.md)
+- [AnteHandler](./ante_handler.md)
+  - [AnteHandler v1](./ante_handler_v1.md)
+  - [AnteHandler v2](./ante_handler_v2.md)
+- [Fraud Proofs](./fraud_proofs.md)
+- [Networking](./networking.md)
+- [Public-Key Cryptography](./public_key_cryptography.md)
+- [Data Square Layout](./data_square_layout.md)
+- [Resource Pricing](./resource_pricing.md)
+- [Multisig](./multisig.md)
+- [State Machine Modules](./state_machine_modules.md)
+  - [State Machine Modules v1](./state_machine_modules_v1.md)
+  - [State Machine Modules v2](./state_machine_modules_v2.md)
+- [Parameters](./parameters.md)
+  - [Parameters v1](./parameters_v1.md)
+  - [Parameters v2](./parameters_v2.md)

specs/src/ante_handler.md

@@ -0,0 +1,13 @@
+# AnteHandler
+
+Celestia makes use of a Cosmos SDK [AnteHandler](https://github.com/cosmos/cosmos-sdk/blob/v0.46.15/x/auth/spec/03_antehandlers.md) in order to reject decodable sdk.Txs that do not meet certain criteria. The AnteHandler 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 is defined in `app/ante/ante.go`. The app version impacts AnteHandler behavior. See:
+
+- [AnteHandler v1](./ante_handler_v1.md)
+- [AnteHandler v2](./ante_handler_v2.md)

specs/src/ante_handler_v1.md

@@ -0,0 +1,23 @@
+# AnteHandler v1
+
+The AnteHandler chains together several decorators to ensure the following criteria are met for app version 1:
+
+- 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://github.com/cosmos/cosmos-sdk/blob/v0.46.15/x/feegrant/README.md) 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 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 smallest denomination of gas price in the tx and set in context.
+- The nonce of all tx signers is incremented by 1.

specs/src/ante_handler_v2.md

@@ -0,0 +1,25 @@
+# AnteHandler v2
+
+The AnteHandler chains together several decorators to ensure the following criteria are met for app version 2:
+
+- The tx does not contain any messages that are unsupported by the current app version. See `MsgVersioningGateKeeper`.
+- 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://github.com/cosmos/cosmos-sdk/blob/v0.46.15/x/feegrant/README.md) module is enabled.
+- The tx's gas price is >= the network minimum gas price where [`NetworkMinGasPrice = 0.000001` utia](https://github.com/celestiaorg/celestia-app/blob/8caa5807df8d15477554eba953bd056ae72d4503/pkg/appconsts/v2/app_consts.go#L9).
+- 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 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 share count is <= the max blob share count. The max blob share count 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 smallest denomination of gas price in the tx and set in context.
+- The nonce of all tx signers is incremented by 1.

specs/src/block_proposer.md

@@ -0,0 +1,24 @@
+# Honest Block Proposer
+
+<!-- toc -->
+
+This document describes the tasks of an honest block proposer to assemble a new block. Performing these actions is not enforced by the [consensus rules](./consensus.md), so long as a valid block is produced.
+
+## Deciding on a Block Size
+
+Before [arranging available data into shares](./data_structures.md#arranging-available-data-into-shares), the size of the original data's square must be determined.
+
+There are two restrictions on the original data's square size:
+
+1. It must be at most [`AVAILABLE_DATA_ORIGINAL_SQUARE_MAX`](./consensus.md#constants).
+1. It must be a power of 2.
+
+With these restrictions in mind, the block proposer performs the following actions:
+
+1. Collect as many transactions and blobs from the mempool as possible, such that the total number of shares is at most [`AVAILABLE_DATA_ORIGINAL_SQUARE_MAX`](./consensus.md#constants).
+1. Compute the smallest square size that is a power of 2 that can fit the number of shares.
+1. Attempt to lay out the collected transactions and blobs in the current square.
+    1. If the square is too small to fit all transactions and blobs (which may happen [due to needing to insert padding between blobs](./data_square_layout.md)) and the square size is smaller than [`AVAILABLE_DATA_ORIGINAL_SQUARE_MAX`](./consensus.md#constants), double the size of the square and repeat the above step.
+    1. If the square is too small to fit all transactions and blobs (which may happen [due to needing to insert padding between blobs](./data_square_layout.md)) and the square size is at [`AVAILABLE_DATA_ORIGINAL_SQUARE_MAX`](./consensus.md#constants), drop the transactions and blobs until the data fits within the square.
+
+Note: the maximum padding shares between blobs should be at most twice the number of blob shares. Doubling the square size (i.e. quadrupling the number of shares in the square) should thus only have to happen at most once.

specs/src/block_validity_rules.md

@@ -0,0 +1,66 @@
+# 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 their
+design. More information on how light clients can check the invalidity of a
+block can be found 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
+availability 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 specific validity rules can be categorized into multiple groups:
+
+### Block Rules
+
+1. In `Block.Data.Txs`, all `BlobTx` transactions must be ordered after non-`BlobTx` transactions.
+
+### Transaction Validity Rules
+
+#### App Version 1
+
+There is no validity rule that transactions must be decodable so the following rules only apply to transactions that are decodable.
+
+1. Decodable transactions must pass all [AnteHandler](./ante_handler.md) checks.
+1. Decodable non-`BlobTx` transactions must not contain a `MsgPayForBlobs` message.
+1. Decodable `BlobTx` transactions must be valid according to the [BlobTx validity rules](../../x/blob/README.md#validity-rules).
+
+#### App Version 2
+
+1. All transactions must be decodable.
+1. All transactions must pass all [AnteHandler](./ante_handler.md) checks.
+1. Non-`BlobTx` transactions must not contain a `MsgPayForBlobs` message.
+1. `BlobTx` transactions must be valid according to the [BlobTx validity rules](../../x/blob/README.md#validity-rules).
+
+### Data Root Construction
+
+The data root must be calculated from a correctly constructed data square per the [data square layout](./data_square_layout.md) rules.
+
+<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"/>