blob

README

x/blob

Abstract

The x/blob module enables users to pay for arbitrary data to be published to the Celestia blockchain. Users create a single BlobTx that is composed of:

1. Blob (Binary Large OBject): the data they wish to publish
2. NamespaceId: the namespace they wish to publish to
3. ShareCommitment: a signature and a commitment over their data when encoded into shares
4. MsgPayForBlobTx: a sdk.Tx that contains a MsgPayForBlob that pays for the inclusion of the blob.

After the BlobTx is submitted to the network, a block producer separates their transaction into a MsgPayForBlob which doesn't include their data (a.k.a blob). Both components get included in the data square in different namespaces: the MsgPayForBlob gets included in the transaction namespace and the associated blob gets included in the namespace the user specified in the original BlobTx. Further reading: Message Block Layout

After a block has been created, the user can verify that their data was included in a block via a blob inclusion proof. A blob inclusion proof uses the ShareCommitment in the original MsgPayForBlob and subtree roots of the block's data square to prove to the user that the shares that compose their original data do in fact exist in a particular block.

State

The blob module doesn't maintain it's own state.

When a MsgPayForBlob is processed, it consumes gas based on the blob size.

Messages

• MsgPayForBlob pays for the blob to be included in the block.

PrepareProposal

The malleation process occurs during the PrepareProposal step.

Events

The blob module emits the following events:

Blob Events

EventPayForBlob

Attribute Key	Attribute Value
signer	{bech32 encoded signer address}
blob_size	{size in bytes}

Parameters

Key	Type	Example
MinSquareSize	uint32	1
MaxSquareSize	uint32	128

Usage

celestia-app tx blob payForBlob <hex encoded namespace> <hex encoded data> [flags]

For submitting PFB transaction via a light client's rpc, see celestia-node's documention.

While not directly supported, the steps in the SubmitPayForBlob function can be reverse engineered to submit blobs programmatically.

How is the MessageShareCommitment generated?

1. Split the blob into shares of size appconsts.ShareSize
2. Determine the msgMinSquareSize (the minimum square size the blob can fit into). This is done by taking the number of shares from the previous step and rounding up to the next perfect square that is a power of two.
3. Arrange the shares into a Merkle mountain range where each tree in the mountain range has a maximum size of the msgMinSquareSize.
4. Take the roots of the trees in the Merkle mountain range and create a new Merkle tree.
5. The share commitment is the Merkle root of the Merkle tree from the previous step.

Documentation

Overview

blob 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.

Index

• func ExportGenesis(ctx sdk.Context, k keeper.Keeper) *types.GenesisState
• func InitGenesis(ctx sdk.Context, k keeper.Keeper, genState types.GenesisState)
• func NewHandler(k keeper.Keeper) sdk.Handler
• func SubmitPayForBlob(ctx context.Context, signer *types.KeyringSigner, conn *grpc.ClientConn, ...) (*sdk.TxResponse, error)
• type AppModule
  • func NewAppModule(cdc codec.Codec, keeper keeper.Keeper) AppModule
  • func (am AppModule) BeginBlock(_ sdk.Context, _ abci.RequestBeginBlock)
  • func (AppModule) ConsensusVersion() uint64
  • func (am AppModule) EndBlock(_ sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate
  • func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage
  • func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, gs json.RawMessage) []abci.ValidatorUpdate
  • func (am AppModule) LegacyQuerierHandler(legacyQuerierCdc *codec.LegacyAmino) sdk.Querier
  • func (am AppModule) Name() string
  • func (AppModule) QuerierRoute() string
  • func (am AppModule) RegisterInvariants(_ sdk.InvariantRegistry)
  • func (am AppModule) RegisterServices(cfg module.Configurator)
  • func (am AppModule) Route() sdk.Route
• type AppModuleBasic
  • func NewAppModuleBasic(cdc codec.BinaryCodec) AppModuleBasic
  • func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage
  • func (AppModuleBasic) GetQueryCmd() *cobra.Command
  • func (a AppModuleBasic) GetTxCmd() *cobra.Command
  • func (AppModuleBasic) Name() string
  • func (AppModuleBasic) RegisterCodec(cdc *codec.LegacyAmino)
  • func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux)
  • func (a AppModuleBasic) RegisterInterfaces(reg cdctypes.InterfaceRegistry)
  • func (AppModuleBasic) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)
  • func (AppModuleBasic) RegisterRESTRoutes(clientCtx client.Context, rtr *mux.Router)
  • func (AppModuleBasic) ValidateGenesis(cdc codec.JSONCodec, config client.TxEncodingConfig, bz json.RawMessage) error

Functions

func ExportGenesis

func ExportGenesis(ctx sdk.Context, k keeper.Keeper) *types.GenesisState

ExportGenesis returns the capability module's exported genesis.

func InitGenesis

func InitGenesis(ctx sdk.Context, k keeper.Keeper, genState types.GenesisState)

InitGenesis initializes the capability module's state from a provided genesis state.

func NewHandler

func NewHandler(k keeper.Keeper) sdk.Handler

NewHandler uses the provided blob keeper to create an sdk.Handler

func SubmitPayForBlob

func SubmitPayForBlob(
	ctx context.Context,
	signer *types.KeyringSigner,
	conn *grpc.ClientConn,
	blobs []*types.Blob,
	gasLim uint64,
	opts ...types.TxBuilderOption,
) (*sdk.TxResponse, error)

SubmitPayForBlob builds, signs, and synchronously submits a PayForBlob transaction. It returns a sdk.TxResponse after submission.

Types

type AppModule

type AppModule struct {
	AppModuleBasic
	// contains filtered or unexported fields
}

AppModule implements the AppModule interface for the capability module.

func NewAppModule

func NewAppModule(cdc codec.Codec, keeper keeper.Keeper) AppModule

func (AppModule) BeginBlock

func (am AppModule) BeginBlock(_ sdk.Context, _ abci.RequestBeginBlock)

BeginBlock executes all ABCI BeginBlock logic respective to the capability module.

func (AppModule) ConsensusVersion

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements ConsensusVersion.

func (AppModule) EndBlock

func (am AppModule) EndBlock(_ sdk.Context, _ abci.RequestEndBlock) []abci.ValidatorUpdate

EndBlock executes all ABCI EndBlock logic respective to the capability module. It returns an empty list of validator updates.

func (AppModule) ExportGenesis

func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage

ExportGenesis returns the capability module's exported genesis state as raw JSON bytes.

func (AppModule) InitGenesis

func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, gs json.RawMessage) []abci.ValidatorUpdate

InitGenesis performs the capability module's genesis initialization. It returns an empty list of validator updates.

func (AppModule) LegacyQuerierHandler

func (am AppModule) LegacyQuerierHandler(legacyQuerierCdc *codec.LegacyAmino) sdk.Querier

LegacyQuerierHandler returns the capability module's Querier.

func (AppModule) Name

func (am AppModule) Name() string

Name returns the capability module's name.

func (AppModule) QuerierRoute

func (AppModule) QuerierRoute() string

QuerierRoute returns the capability module's query routing key.

func (AppModule) RegisterInvariants

func (am AppModule) RegisterInvariants(_ sdk.InvariantRegistry)

RegisterInvariants registers the capability module's invariants.

func (AppModule) RegisterServices

func (am AppModule) RegisterServices(cfg module.Configurator)

RegisterServices registers a GRPC query service to respond to the module-specific GRPC queries.

func (AppModule) Route

func (am AppModule) Route() sdk.Route

Route returns the capability module's message routing key.

type AppModuleBasic

type AppModuleBasic struct {
	// contains filtered or unexported fields
}

AppModuleBasic implements the AppModuleBasic interface for the capability module.

func NewAppModuleBasic

func NewAppModuleBasic(cdc codec.BinaryCodec) AppModuleBasic

func (AppModuleBasic) DefaultGenesis

func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage

DefaultGenesis returns the capability module's default genesis state.

func (AppModuleBasic) GetQueryCmd

func (AppModuleBasic) GetQueryCmd() *cobra.Command

GetQueryCmd returns the capability module's root query command.

func (AppModuleBasic) GetTxCmd

func (a AppModuleBasic) GetTxCmd() *cobra.Command

GetTxCmd returns the capability module's root tx command.

func (AppModuleBasic) Name

func (AppModuleBasic) Name() string

Name returns the capability module's name.

func (AppModuleBasic) RegisterCodec

func (AppModuleBasic) RegisterCodec(cdc *codec.LegacyAmino)

func (AppModuleBasic) RegisterGRPCGatewayRoutes

func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux)

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for the module.

func (AppModuleBasic) RegisterInterfaces

func (a AppModuleBasic) RegisterInterfaces(reg cdctypes.InterfaceRegistry)

RegisterInterfaces registers the module's interface types

func (AppModuleBasic) RegisterLegacyAminoCodec

func (AppModuleBasic) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)

func (AppModuleBasic) RegisterRESTRoutes

func (AppModuleBasic) RegisterRESTRoutes(clientCtx client.Context, rtr *mux.Router)

RegisterRESTRoutes registers the capability module's REST service handlers.

func (AppModuleBasic) ValidateGenesis

func (AppModuleBasic) ValidateGenesis(cdc codec.JSONCodec, config client.TxEncodingConfig, bz json.RawMessage) error

ValidateGenesis performs genesis state validation for the capability module.