docs: add specs

specs/01_concepts.md

@@ -0,0 +1,32 @@
+<!--
+order: 1
+-->
+
+# Concepts
+
+### MaxBlocksLimitForBlob
+
+- The `maxBlocksLimitForBlob` defines the maximum number blobs to be posted to Avail DA at once (in on Avail Transaction).
+
+### Blob Interval
+
+- The `Blob Interval` defines the frequency at which block data is posted to the Avail Network.
+- For example, if the interval is set to `5`, data will be submitted at block heights `6`, `11`, `16`, and so on.
+- At each of these intervals, the block data from the proven height to min(current height, proven height + maxBlocksLimitForBlob) will be posted.
+
+Example:
+For Blob Interval = 5 and Maximum Blocks Limit for Blob = 10 :-
+
+- At height `6` and provenHeight = `0`, blocks from `1` to `5` are posted.
+
+- At height `11` and provenHeight still `0`, blocks from `1` to `10` are posted.
+
+### Relayer
+
+- The `Relayer` acts as the transport layer, responsible for handling requests from the `preBlocker` and facilitating transactions between the Cosmos chain and the Avail DA network.
+- It performs key functions such as submitting block data to Avail and updating block status on the Cosmos chain. Every validator in the network is required to run the relayer process.
+- Relayer should initialized with a chain account so that the validator can use this account to sign `MsgUpdateStatusBlob` transaction.
+
+### Voting Interval
+
+- The `Voting Interval` is the period before validators verify whether data is truly included in Avail and confirm it with the network using vote extensions.

specs/02_state.md

@@ -0,0 +1,64 @@
+<!--
+order: 2
+-->
+
+# State
+
+The module keeps state of the following primary objects:
+
+## Blocks Range
+
+Tracks the start and end of the current blocks range being posted to `Avail`.
+
+### Blocks Range Start Height
+
+Stores the start height of the range of current blocks being posted to `Avail`.
+
+It is stored in the state as follows:
+
+- PrevHeightKey `0x07` -> Start Height (Uint64)
+
+### Blocks Range End Height
+
+Stores the end height of the range of current blocks being posted to `Avail`.
+
+It is stored in the state as follows:
+
+- NextHeightKey `0x08` -> End Height (Uint64)
+
+## Blocks Submission Status
+
+Indicates the status of the current blocks submission (`READY`, `PENDING`, `IN_VOTING`, `FAILURE`).
+
+** PENDING ** : Blocks data submission has been initiated and is awaiting confirmation
+** IN_VOTING ** : Blocks data has been posted to `Avail` and is now pending validators' verification
+** FAILURE ** : Blocks data submission or verification has failed and needs to be resubmitted
+** READY ** : blocks data submission is successful; the next set of blocks is ready to be posted
+
+It is stored in the state as follows:
+
+- BlobStatusKey `0x06` : status (uint32)
+
+## Voting End Height
+
+The block height at which the voting for the current blocks should conclude.
+
+It is stored in the state as follows:
+
+- VotingEndHeightKey `0x09` : voting end block height (uint64)
+
+## Avail Height
+
+The Avail block height at which the latest blocks data is made available.
+
+It is stored in the state as follows:
+
+AvailHeightKey `0x0A` : avail block height (uint64)
+
+## Proven Height
+
+The latest block height of the Cosmos chain for which data has been successfully posted to Avail and verified by the network.
+
+It is stored in the state as follows:
+
+ProvenHeightKey `0x02` : proven block height (uint64)

specs/03_msg.md

@@ -0,0 +1,14 @@
+<!--
+order: 3
+-->
+
+# Messages
+
+## UpdateBlobStatus
+
+The `MsgUpdateBlobStatus` is used to update the status of blocks submission from `PENDING` to either `IN_VOTING` if the submission is successful, or `FAILURE` if it fails. The responsibility for executing this transaction lies with the individual who originally submitted the blocks data to `Avail` (the proposer of the block where the blocks data submission was initiated).
+
+This message will fail under the following conditions:
+
+    If the status is nil, meaning it is neither true nor false.
+    If the status is true but the Avail height is not a valid number.

specs/04_client.md

@@ -0,0 +1,35 @@
+<!--
+order: 4
+-->
+
+# Client
+
+A user can query and interact with the `cada` module using the CLI.
+
+
+## Query
+
+The `query` commands allows users to query `cada` state.
+
+
+```sh
+simd query cada --help
+```
+
+#### Query the Status
+The `get-da-status` command enables users to retrieve comprehensive information, including the range of blocks currently being posted to Avail, the current status, the last proven height, the Avail height where the data is made available, and the voting block height by which voting should conclude.
+
+```sh
+$ simd query cada get-da-status
+```
+
+Output:
+
+```yml
+last_blob_voting_ends_at: "23"
+proven_height: "0"
+range:
+  from: "1"
+  to: "5"
+status: IN_VOTING
+```

specs/05_prepare_proposal.md

@@ -0,0 +1,59 @@
+<!--
+order: 5
+-->
+
+# ProofOfBlobProposalHandler: PrepareProposal Method
+
+This documentation provides an overview of the `PrepareProposal` method within the `ProofOfBlobProposalHandler`. This method is critical for preparing a block proposal by aggregating and injecting vote information into the proposal transactions.
+
+## Method Overview
+
+The `PrepareProposal` method performs the following key steps:
+
+### 1. Proposer Address Initialization
+
+The method starts by setting the `proposerAddress` in the keeper with the address provided in the `RequestPrepareProposal`. This address represents the proposer of the current block. Since the `PrepareProposal` ABCI method is exclusively executed by the block proposer, this address can later be used for posting block data to `Avail`.
+
+```go
+h.keeper.proposerAddress = req.ProposerAddress
+```
+
+
+### 2. Vote Aggregation
+
+The method then aggregates votes by calling the `aggregateVotes` function, which takes in the current context and the `LocalLastCommit` from the request. This function collects votes from the last commit, which are essential for the consensus process for da verification.
+
+```go
+votes, err := h.aggregateVotes(ctx, req.LocalLastCommit)
+if err != nil {
+    fmt.Println("error while aggregating votes", err)
+    return nil, err
+}
+```
+
+
+
+### 3. Injection of Aggregated Votes
+
+The method creates a new structure, `StakeWeightedVotes`, to hold the aggregated votes and the extended commit information (`ExtendedCommitInfo`).
+
+```go
+injectedVoteExtTx := StakeWeightedVotes{
+    Votes:              votes,
+    ExtendedCommitInfo: req.LocalLastCommit,
+}
+bz, err := json.Marshal(injectedVoteExtTx)
+if err != nil {
+    fmt.Println("failed to encode injected vote extension tx", "err", err)
+}
+```
+
+The serialized vote information (`injectedVoteExtTx`) is appended to the list of proposal transactions, which can be later processed in `PreBlocker` abci method.
+
+```go
+proposalTxs = append(proposalTxs, bz)
+
+return &abci.ResponsePrepareProposal{
+    Txs: proposalTxs,
+}, nil
+```

specs/06_preblocker.md

@@ -0,0 +1,83 @@
+<!--
+order: 6
+-->
+
+# ProofOfBlobProposalHandler: PreBlocker Method
+
+This documentation provides a detailed overview of the `PreBlocker` method within the `ProofOfBlobProposalHandler`. This method is crucial for processing vote extensions, updating statuses, and initiating block data submissions to Avail.
+
+## Method Overview
+
+The `PreBlocker` method is responsible for two primary tasks: processing votes from vote extensions to update the status and initiating the submission of blocks' data to Avail. Below is a step-by-step explanation of how this method works.
+
+### 1. Process Votes from Vote Extensions and Update the Status
+
+When the current block height matches the voting end height and the status is `IN_VOTING`, the method processes the voting results and updates the state accordingly.
+
+- **Success Condition:** If the collective voting power exceeds 66%, the status is updated to `READY`, and the `provenHeight` is set to the end of the current block range.
+- **Failure Condition:** If the voting power is 66% or less, the status is updated to `FAILURE`.
+
+```go
+if len(req.Txs) > 0 && currentHeight == int64(votingEndHeight) && blobStatus == IN_VOTING_STATE {
+    var injectedVoteExtTx StakeWeightedVotes
+    if err := json.Unmarshal(req.Txs[0], &injectedVoteExtTx); err != nil {
+        fmt.Println("preblocker failed to decode injected vote extension tx", "err", err)
+    } else {
+        from := k.GetStartHeightFromStore(ctx)
+        to := k.GetEndHeightFromStore(ctx)
+
+        pendingRangeKey := Key(from, to)
+        votingPower := injectedVoteExtTx.Votes[pendingRangeKey]
+
+        if votingPower > 66 { // Voting power is greater than 66%
+            k.setBlobStatusSuccess(ctx)
+        } else {
+            k.SetBlobStatusFailure(ctx)
+        }
+    }
+}
+```
+
+### 2. Initiate Block Data Availability (DA) Submission
+
+If the current block height aligns with a voting interval and the status is either `READY` or `FAILURE`, the method updates the block range and sets the status to `PENDING` for the next round of blocks data submission.
+
+- **Range Calculation:** The pending block range to be submitted is calculated based on the last proven height and the current block height.
+- **Status Update:** The status is set to `PENDING` to mark the start of the data submission process.
+
+```go
+// The following code is executed at block heights that are multiples of the voteInterval,
+// i.e., voteInterval+1, 2*voteInterval+1, 3*voteInterval+1, etc.
+if !k.IsValidBlockToPostTODA(uint64(currentBlockHeight)) {
+    return nil
+}
+
+provenHeight := k.GetProvenHeightFromStore(ctx)
+fromHeight := provenHeight + 1                                                     // Calculate pending range of blocks to post data
+endHeight := min(fromHeight+uint64(k.MaxBlocksForBlob), uint64(ctx.BlockHeight())) // Exclusive range i.e., [fromHeight, endHeight)
+
+sdkCtx := sdk.UnwrapSDKContext(ctx)
+ok := k.SetBlobStatusPending(sdkCtx, fromHeight, endHeight-1)
+if !ok {
+    return nil
+}
+```
+
+### 3. Proposer Submits Block Data to Avail DA
+
+If the node running this method is the proposer of the block, it takes responsibility for submitting the blocks data to Avail DA.
+
+- **Block Data Submission:** The proposer gathers the blocks within the calculated range and posts them to Avail DA.
+
+```go
+var blocksToSubmit []int64
+
+for i := fromHeight; i < endHeight; i++ {
+    blocksToSubmit = append(blocksToSubmit, int64(i))
+}
+
+// Only the proposer should execute the following code
+if bytes.Equal(req.ProposerAddress, k.proposerAddress) {
+    k.relayer.PostBlocks(ctx, blocksToSubmit, k.cdc, req.ProposerAddress)
+}
+```

specs/07_vote_extension.md

@@ -0,0 +1,81 @@
+<!--
+order: 7
+-->
+
+# Vote Extensions
+
+Vote extensions are used to propagate arbitrary data across the network without needing to implement transactions that modify the state. Validators utilize vote extensions to verify data availability of a specific range of blocks and update the state of the Cada module accordingly.
+
+This specification details the functionality and purpose of the `ExtendVoteHandler` and `VerifyVoteExtensionHandler` methods within the VoteExtHandler struct. These methods are part of a voting extension process where validators extend their votes based on the availability of data in the Avail DA network.
+
+### ExtendVoteHandler
+
+The `ExtendVoteHandler` method is responsible for generating a `vote extension`. It checks the availability of specific data in the Avail by interacting with an Avail light client. The vote extension is then created based on the outcome of this check.
+
+* The method first begins by retrieving several voting-related parameters, including the start and end heights of the blocks being processed, the Avail block height, and the status of the current blob (data)
+
+```go
+from := h.Keeper.GetStartHeightFromStore(ctx)
+		end := h.Keeper.GetEndHeightFromStore(ctx)
+
+		availHeight := h.Keeper.GetAvailHeightFromStore(ctx)
+
+		pendingRangeKey := Key(from, end)
+
+		blobStatus := h.Keeper.GetBlobStatus(ctx)
+		currentHeight := ctx.BlockHeight()
+		voteEndHeight := h.Keeper.GetVotingEndHeightFromStore(ctx)
+```
+
+* The method checks if the current height is just before the end of the voting period and if the blob is in the voting state. If not, it generates a basic vote extension indicating that no data was verified
+
+```go
+if currentHeight+1 != int64(voteEndHeight) || blobStatus != IN_VOTING_STATE {
+			voteExt := VoteExtension{
+				Votes: Votes,
+			}
+
+			// json marshalling
+			votesBytes, err := json.Marshal(voteExt)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal vote extension: %w", err)
+			}
+			abciResponseVoteExt.VoteExtension = votesBytes
+			return abciResponseVoteExt, nil
+		}
+```
+
+* If the conditions are met, the method queries the Avail light client to determine if the relevant data is available. The result of this check is recorded in a map
+```go
+    ok, err := h.Keeper.relayer.IsDataAvailable(ctx, from, end, availHeight, "http://localhost:8000")
+		if ok {
+			h.logger.Info("submitted data to Avail verified successfully at",
+				"block_height", availHeight,
+			)
+		}
+
+
+		Votes[pendingRangeKey] = ok
+```
+
+* The outcome (whether the data was available or not) is marshaled into a vote extension and returned as part of the abci.ResponseExtendVote
+
+```go
+    voteExt := VoteExtension{
+			Votes: Votes,
+		}
+
+		votesBytes, err := json.Marshal(voteExt)
+		if err != nil {
+			return nil, fmt.Errorf("failed to marshal vote extension: %w", err)
+		}
+
+		return &abci.ResponseExtendVote{
+			VoteExtension: votesBytes,
+		}, nil
+```
+
+### VerifyVoteExtensionHandler
+The `VerifyVoteExtensionHandler` method is responsible for validating the format and content of the vote extensions generated by the `ExtendVoteHandler`.
+
+This method performs a basic validation check on the received vote extension, ensuring it meets the necessary format requirements. It then returns a response indicating whether the vote extension is accepted.