wip: docs for payment module

x/payment/client/cli/query.go

@@ -2,18 +2,13 @@ package cli
 
 import (
 	"fmt"
-	// "strings"
-
-	"github.com/spf13/cobra"
-
-	"github.com/cosmos/cosmos-sdk/client"
-	// "github.com/cosmos/cosmos-sdk/client/flags"
-	// sdk "github.com/cosmos/cosmos-sdk/types"
 
 	"github.com/celestiaorg/celestia-app/x/payment/types"
+	"github.com/cosmos/cosmos-sdk/client"
+	"github.com/spf13/cobra"
 )
 
-// GetQueryCmd returns the cli query commands for this module
+// GetQueryCmd returns the CLI query commands for this module
 func GetQueryCmd(queryRoute string) *cobra.Command {
 	// Group payment queries under a subcommand
 	cmd := &cobra.Command{

x/payment/client/cli/tx.go

@@ -4,11 +4,9 @@ import (
 	"fmt"
 	"time"
 
-	"github.com/spf13/cobra"
-
-	"github.com/cosmos/cosmos-sdk/client"
-	// "github.com/cosmos/cosmos-sdk/client/flags"
 	"github.com/celestiaorg/celestia-app/x/payment/types"
+	"github.com/cosmos/cosmos-sdk/client"
+	"github.com/spf13/cobra"
 )
 
 var DefaultRelativePacketTimeoutTimestamp = uint64((time.Duration(10) * time.Minute).Nanoseconds())

x/payment/doc.go

@@ -0,0 +1,4 @@
+// payment is a Cosmos SDK module that enables users to pay for data to be
+// published to the Celestia blockchain. Please see ./specs/docs.md for the full
+// specification of this module.
+package payment

x/payment/keeper/keeper.go

@@ -13,7 +13,7 @@ import (
 
 const payForDataGasDescriptor = "pay for data"
 
-// Keeper handles all the state changes for the celestia-app module.
+// Keeper handles all the state changes for the payment module.
 type Keeper struct {
 	cdc codec.BinaryCodec
 }
@@ -28,7 +28,8 @@ func (k Keeper) Logger(ctx sdk.Context) log.Logger {
 	return ctx.Logger().With("module", fmt.Sprintf("x/%s", types.ModuleName))
 }
 
-// MsgPayForData moves a user's coins to the module address and burns them.
+// PayForData moves a user's coins to the module address and burns them.
+// TODO fix this comment because it appears inaccurate.
 func (k Keeper) PayForData(goCtx context.Context, msg *types.MsgPayForData) (*types.MsgPayForDataResponse, error) {
 	ctx := sdk.UnwrapSDKContext(goCtx)
 

x/payment/module.go

@@ -133,8 +133,8 @@ func (am AppModule) RegisterServices(cfg module.Configurator) {
 // RegisterInvariants registers the capability module's invariants.
 func (am AppModule) RegisterInvariants(_ sdk.InvariantRegistry) {}
 
-// InitGenesis performs the capability module's genesis initialization It returns
-// no validator updates.
+// InitGenesis performs the capability module's genesis initialization. It
+// returns no validator updates.
 func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, gs json.RawMessage) []abci.ValidatorUpdate {
 	var genState types.GenesisState
 	// Initialize global index to index in genesis state

x/payment/payfordata.go

@@ -13,8 +13,8 @@ import (
 	"github.com/celestiaorg/nmt/namespace"
 )
 
-// SubmitPayForData constructs, signs and synchronously submits a PayForData
-// transaction, returning a sdk.TxResponse upon submission.
+// SubmitPayForData builds, signs, and synchronously submits a PayForData
+// transaction. It returns a sdk.TxResponse after submission.
 func SubmitPayForData(
 	ctx context.Context,
 	signer *types.KeyringSigner,
@@ -48,7 +48,7 @@ func SubmitPayForData(
 	return txResp.TxResponse, nil
 }
 
-// BuildPayForData constructs a PayForData transaction.
+// BuildPayForData builds a PayForData transaction.
 func BuildPayForData(
 	ctx context.Context,
 	signer *types.KeyringSigner,

x/payment/spec/docs.md

@@ -1,23 +1,21 @@
-# Abstract
+# `x/payment`
 
-The payment module is responsible for paying for arbitrary data that will be added to the Celestia blockchain. While the data being submitted can be arbitrary, the exact placement of that data is important for the transaction to be valid. This is why the payment module utilizes a malleated transaction scheme. Malleated transactions allow for users to create a single transaction, that can later be malleated by the block producer to create a variety of different valid transactions that are still signed over by the user. To accomplish this, users create a single `MsgWirePayForData` transaction, which is composed of metadata and signatures for multiple variations of the transaction that will be included onchain. After the transaction is submitted to the network, the block producer selects the appropriate signature and creates a valid `MsgPayForData` transaction depending on the square size for that block. This new malleated `MsgPayForData` transaction is what ends up onchain.
+## Abstract
+
+The payment module is responsible for paying for arbitrary data to be published to the Celestia blockchain. While the data being submitted can be arbitrary, the exact placement of that data is important for the transaction to be valid. This is why the payment module utilizes a malleated transaction scheme. Malleated transactions allow for users to create a single transaction, that can later be malleated by the block producer to create a variety of different valid transactions that are still signed over by the user. To accomplish this, users create a single `MsgWirePayForData` transaction that is composed of metadata and a signature for the transaction that will be included on-chain. After the transaction is submitted to the network, the block producer selects the appropriate signature and creates a valid `MsgPayForData` transaction depending on the square size for that block. This new malleated `MsgPayForData` transaction is what ends up onchain.
 
 Further reading: [Message Block Layout](https://github.com/celestiaorg/celestia-specs/blob/master/src/rationale/message_block_layout.md)
 
 ## State
 
-- The sender’s account balance, via the bank keeper’s [`Burn`](https://github.com/cosmos/cosmos-sdk/blob/531bf5084516425e8e3d24bae637601b4d36a191/x/bank/spec/01_state.md) method.
-- The standard incrememnt of the sender's account number via the [auth module](https://github.com/cosmos/cosmos-sdk/blob/531bf5084516425e8e3d24bae637601b4d36a191/x/auth/spec/02_state.md).
-
-## Messages
-
-- [`MsgWirePayForData`](https://github.com/celestiaorg/celestia-app/blob/b4c8ebdf35db200a9b99d295a13de01110802af4/x/payment/types/tx.pb.go#L32-L40)
+The payment module doesn't maintain it's own state.
 
-While this transaction is created and signed by the user, it never actually ends up onchain. Instead, it is used to create a new "malleated" transaction that does get included onchain.
+When a PayForData message is processed, it consumes gas based on the message size.
 
-- [`MsgPayForData`](https://github.com/celestiaorg/celestia-app/blob/b4c8ebdf35db200a9b99d295a13de01110802af4/x/payment/types/tx.pb.go#L208-L216)
+## Messages
 
-The malleated transaction that is created from metadata contained in the original `MsgWirePayForData`. It also burns some of the sender’s funds.
+- [`MsgWirePayForData`](https://github.com/celestiaorg/celestia-app/blob/29e0a2751182499f7dc03598eabfc8d049ae62cb/x/payment/types/tx.pb.go#L32-L40) is a message that is created and signed by the user but it never ends up on-chain. It is used to create a new "malleated" transaction that does get included on-chain.
+- [`MsgPayForData`](https://github.com/celestiaorg/celestia-app/blob/29e0a2751182499f7dc03598eabfc8d049ae62cb/x/payment/types/tx.pb.go#L209-L219) is a malleated transaction that is created from metadata contained in the original `MsgWirePayForData`.
 
 ## PrepareProposal
 
@@ -103,15 +101,16 @@ There are no parameters yet, but we might add
 
 - BaseFee
 - SquareSize
-- ShareSize
 
 ### Usage
 
-`celestia-app tx payment payForData <hex encoded namespace> <hex encoded data> [flags]`
+```shell
+celestia-app tx payment payForData <hex encoded namespace> <hex encoded data> [flags]
+```
 
 ### Programmatic Usage
 
-There are tools to programmatically create, sign, and broadcast `MsgWirePayForDatas`
+There are tools to programmatically create, sign, and broadcast `MsgWirePayForData`s
 
 ```go
 // create the raw WirePayForData transaction

x/payment/types/events.go

@@ -13,7 +13,7 @@ const (
 	AttributeKeySize   = "size"
 )
 
-// NewPayForDataEvent constructs a new payformessge sdk.Event
+// NewPayForDataEvent constructs a new payfordata sdk.Event
 func NewPayForDataEvent(signer string, size uint64) sdk.Event {
 	return sdk.NewEvent(
 		EventTypePayForData,