docs(core): add core documentation and principles (cosmos#21511)

Co-authored-by: Aaron Craelius <[email protected]>

core/README.md

@@ -1,11 +1,19 @@
 # Cosmos SDK Core
 
-The [cosmossdk.io/core](https://pkg.go.dev/cosmossdk.io/core) go module defines
-"core" functionality for the Cosmos SDK.
+The [cosmossdk.io/core](https://pkg.go.dev/cosmossdk.io/core) Go module defines essential APIs and interfaces for the Cosmos SDK ecosystem. It serves as a foundation for building modular blockchain applications.
 
-Currently functionality for registering modules using the [appmodule](https://pkg.go.dev/cosmossdk.io/core/appmodule) 
-package and composing apps using the [appconfig](https://pkg.go.dev/cosmossdk.io/core/appconfig)
-package is provided.
+Key features and principles:
 
-In the future core functionality for building Cosmos SDK app modules will be
-provided in this go module.
+1. Provides stable, long-term maintained APIs for module development and app composition.
+2. Focuses on interface definitions without implementation details.
+3. Implementations are housed in the runtime(/v2) or individual modules.
+4. Modules depend solely on core APIs for maximum compatibility.
+5. New API additions undergo thorough consideration to maintain stability.
+6. Adheres to a no-breaking-changes policy for reliable dependency management.
+7. Aimed to have zero dependencies, ensuring a lightweight and self-contained foundation.
+
+The core module offers the [appmodule](https://pkg.go.dev/cosmossdk.io/core/appmodule) and [appmodule/v2](https://pkg.go.dev/cosmossdk.io/core/appmodule/v2) packages that include APIs to describe how modules can be written.
+Additionally, it contains all core services APIs that can be used in modules to interact with the SDK, majoritarily via the `appmodule.Environment` struct.
+Last but not least, it provides codecs and packages for the Cosmos SDK's core types (think of, for instance, logger, store interface or an address codec).
+
+Developers and contributors approach core API design with careful deliberation, ensuring that additions provide significant value while maintaining the module's stability and simplicity.

core/appmodule/doc.go

@@ -1,5 +1,4 @@
-// Package appmodule defines the functionality for registering Cosmos SDK app
-// modules that are assembled using the cosmossdk.io/depinject
-// dependency injection system and the declarative app configuration format
-// handled by the appconfig package.
+// Package appmodule defines what is needed for an module to be used in the Cosmos SDK (runtime).
+// It is equivalent to the appmodulev2 package, but less flexible to stay compatible with baseapp instead of server/v2.
+// If you are looking at integrating dependency injection into your module please see depinject appconfig documentation.
 package appmodule

core/appmodule/environment.go

@@ -1,9 +1,9 @@
 package appmodule
 
 import (
-	"cosmossdk.io/core/appmodule/v2"
+	appmodulev2 "cosmossdk.io/core/appmodule/v2"
 )
 
-// Environment is used to get all services to their respective module
-// Contract: All fields of environment are always populated.
-type Environment = appmodule.Environment
+// Environment is used to get all services to their respective module.
+// Contract: All fields of environment are always populated by runtime.
+type Environment = appmodulev2.Environment

core/appmodule/genesis.go

@@ -5,7 +5,7 @@ import (
 	"encoding/json"
 	"io"
 
-	"cosmossdk.io/core/appmodule/v2"
+	appmodulev2 "cosmossdk.io/core/appmodule/v2"
 )
 
 // HasGenesisBasics is the legacy interface for stateless genesis methods.
@@ -15,18 +15,18 @@ type HasGenesisBasics interface {
 }
 
 // HasGenesis defines a custom genesis handling API implementation.
-type HasGenesis = appmodule.HasGenesis
+type HasGenesis = appmodulev2.HasGenesis
 
 // HasABCIGenesis defines a custom genesis handling API implementation for ABCI.
 // (stateful genesis methods which returns validator updates)
 // Most modules should not implement this interface.
-type HasABCIGenesis = appmodule.HasABCIGenesis
+type HasABCIGenesis = appmodulev2.HasABCIGenesis
 
 // HasGenesisAuto is the extension interface that modules should implement to handle
 // genesis data and state initialization.
-// WARNING: This interface is experimental and may change at any time.
+// WARNING: This interface is experimental and may change at any time and has been dropped in v2.
 type HasGenesisAuto interface {
-	appmodule.AppModule
+	appmodulev2.AppModule
 
 	// DefaultGenesis writes the default genesis for this module to the target.
 	DefaultGenesis(GenesisTarget) error

core/appmodule/migrations.go

@@ -1,20 +1,20 @@
 package appmodule
 
 import (
-	"cosmossdk.io/core/appmodule/v2"
+	appmodulev2 "cosmossdk.io/core/appmodule/v2"
 )
 
 // HasConsensusVersion is the interface for declaring a module consensus version.
-type HasConsensusVersion = appmodule.HasConsensusVersion
+type HasConsensusVersion = appmodulev2.HasConsensusVersion
 
 // HasMigrations is implemented by a module which upgrades or has upgraded to a new consensus version.
-type HasMigrations = appmodule.HasMigrations
+type HasMigrations = appmodulev2.HasMigrations
 
 // MigrationRegistrar is the interface for registering in-place store migrations.
-type MigrationRegistrar = appmodule.MigrationRegistrar
+type MigrationRegistrar = appmodulev2.MigrationRegistrar
 
 // MigrationHandler is the migration function that each module registers.
-type MigrationHandler = appmodule.MigrationHandler
+type MigrationHandler = appmodulev2.MigrationHandler
 
 // VersionMap is a map of moduleName -> version
-type VersionMap = appmodule.VersionMap
+type VersionMap = appmodulev2.VersionMap

core/appmodule/module.go

@@ -3,33 +3,33 @@ package appmodule
 import (
 	"context"
 
-	"cosmossdk.io/core/appmodule/v2"
+	appmodulev2 "cosmossdk.io/core/appmodule/v2"
 	"cosmossdk.io/core/legacy"
 )
 
 // AppModule is a tag interface for app module implementations to use as a basis
 // for extension interfaces. It provides no functionality itself, but is the
 // type that all valid app modules should provide so that they can be identified
 // by other modules (usually via depinject) as app modules.
-type AppModule = appmodule.AppModule
+type AppModule = appmodulev2.AppModule
 
 // HasPreBlocker is the extension interface that modules should implement to run
 // custom logic before BeginBlock.
-type HasPreBlocker = appmodule.HasPreBlocker
+type HasPreBlocker = appmodulev2.HasPreBlocker
 
 // HasBeginBlocker is the extension interface that modules should implement to run
 // custom logic before transaction processing in a block.
-type HasBeginBlocker = appmodule.HasBeginBlocker
+type HasBeginBlocker = appmodulev2.HasBeginBlocker
 
 // HasEndBlocker is the extension interface that modules should implement to run
 // custom logic after transaction processing in a block.
-type HasEndBlocker = appmodule.HasEndBlocker
+type HasEndBlocker = appmodulev2.HasEndBlocker
 
 // HasRegisterInterfaces is the interface for modules to register their msg types.
-type HasRegisterInterfaces = appmodule.HasRegisterInterfaces
+type HasRegisterInterfaces = appmodulev2.HasRegisterInterfaces
 
 // ValidatorUpdate defines a validator update.
-type ValidatorUpdate = appmodule.ValidatorUpdate
+type ValidatorUpdate = appmodulev2.ValidatorUpdate
 
 // HasServices is the extension interface that modules should implement to register
 // implementations of services defined in .proto files.
@@ -55,13 +55,13 @@ type ValidatorUpdate = appmodule.ValidatorUpdate
 // HasPrepareCheckState is an extension interface that contains information about the AppModule
 // and PrepareCheckState.
 type HasPrepareCheckState interface {
-	appmodule.AppModule
+	appmodulev2.AppModule
 	PrepareCheckState(context.Context) error
 }
 
 // HasPrecommit is an extension interface that contains information about the appmodule.AppModule and Precommit.
 type HasPrecommit interface {
-	appmodule.AppModule
+	appmodulev2.AppModule
 	Precommit(context.Context) error
 }
 

core/appmodule/v2/doc.go

@@ -0,0 +1,3 @@
+// Package appmodule defines what is needed for an module to be used in the Cosmos SDK (runtime/v2).
+// If you are looking at integrating dependency injection into your module please see depinject appconfig documentation.
+package appmodulev2

core/appmodule/v2/environment.go

@@ -1,4 +1,4 @@
-package appmodule
+package appmodulev2
 
 import (
 	"cosmossdk.io/core/branch"
@@ -11,8 +11,8 @@ import (
 	"cosmossdk.io/core/transaction"
 )
 
-// Environment is used to get all services to their respective module
-// Contract: All fields of environment are always populated.
+// Environment is used to get all services to their respective module.
+// Contract: All fields of environment are always populated by runtime.
 type Environment struct {
 	Logger log.Logger
 

core/appmodule/v2/genesis.go

@@ -1,4 +1,4 @@
-package appmodule
+package appmodulev2
 
 import (
 	"context"

core/appmodule/v2/handlers.go

@@ -1,4 +1,4 @@
-package appmodule
+package appmodulev2
 
 import (
 	"context"

core/appmodule/v2/migrations.go

@@ -1,4 +1,4 @@
-package appmodule
+package appmodulev2
 
 import "context"
 

core/appmodule/v2/module.go

@@ -1,4 +1,4 @@
-package appmodule
+package appmodulev2
 
 import (
 	"context"

core/appmodule/v2/tx_validator.go

@@ -1,4 +1,4 @@
-package appmodule
+package appmodulev2
 
 import (
 	"context"

core/context/context.go

@@ -12,8 +12,8 @@ var (
 	ExecModeKey = execModeKey{}
 	// CometInfoKey is the context key for allowing modules to get CometInfo.
 	CometInfoKey = cometInfoKey{}
-	// InitInfoKey is the context key for setting consensus params from genesis in the consensus module.
-	InitInfoKey = initInfoKey{}
+	// CometParamsInitInfoKey is the context key for setting consensus params from genesis in the consensus module.
+	CometParamsInitInfoKey = initInfoKey{}
 
 	// EnvironmentContextKey is the context key for the environment.
 	// A caller should not assume the environment is available in each context.

core/context/server_context.go

@@ -6,6 +6,8 @@ type (
 )
 
 var (
+	// LoggerContextKey is the context key where the logger can be found.
 	LoggerContextKey loggerContextKey
-	ViperContextKey  viperContextKey
+	// ViperContextKey is the context key where the viper instance can be found.
+	ViperContextKey viperContextKey
 )

core/gas/service.go

@@ -42,6 +42,7 @@ type Meter interface {
 	Limit() Gas
 }
 
+// GasConfig defines the gas costs for the application.
 type GasConfig struct {
 	HasCost          Gas
 	DeleteCost       Gas

core/genesis/doc.go

@@ -0,0 +1,3 @@
+// package genesis is used to define appmodule.HasGenesisAuto experimental auto genesis.
+// This genesis package isn't supported in server/v2.
+package genesis

core/legacy/amino.go

@@ -1,5 +1,6 @@
 package legacy
 
+// Amino is an interface that allow to register concrete types and interfaces with the Amino codec.
 type Amino interface {
 	// RegisterInterface registers an interface and its concrete type with the Amino codec.
 	RegisterInterface(interfacePtr any, iopts *InterfaceOptions)
@@ -8,6 +9,7 @@ type Amino interface {
 	RegisterConcrete(cdcType interface{}, name string)
 }
 
+// InterfaceOptions defines options for registering an interface with the Amino codec.
 type InterfaceOptions struct {
 	Priority           []string // Disamb priority.
 	AlwaysDisambiguate bool     // If true, include disamb for all types.

core/registry/legacy.go

@@ -4,6 +4,8 @@ import (
 	"cosmossdk.io/core/transaction"
 )
 
+// InterfaceRegistrar is an interface for registering interfaces and their implementation.
+// It is a subset of the Cosmos SDK InterfaceRegistry for registration only.
 type InterfaceRegistrar interface {
 	// RegisterInterface associates protoName as the public name for the
 	// interface passed in as iface. This is to be used primarily to create

core/transaction/service.go

@@ -20,5 +20,6 @@ const (
 
 // Service creates a transaction service.
 type Service interface {
+	// ExecMode returns the current execution mode.
 	ExecMode(ctx context.Context) ExecMode
 }

core/transaction/transaction.go

@@ -19,6 +19,8 @@ type Codec[T Tx] interface {
 	DecodeJSON([]byte) (T, error)
 }
 
+// Tx defines the interface for a transaction.
+// All custom transactions must implement this interface.
 type Tx interface {
 	// Hash returns the unique identifier for the Tx.
 	Hash() [32]byte

server/v2/cometbft/abci.go

@@ -245,7 +245,7 @@ func (c *Consensus[T]) InitChain(ctx context.Context, req *abciproto.InitChainRe
 	}
 
 	if req.ConsensusParams != nil {
-		ctx = context.WithValue(ctx, corecontext.InitInfoKey, &consensustypes.MsgUpdateParams{
+		ctx = context.WithValue(ctx, corecontext.CometParamsInitInfoKey, &consensustypes.MsgUpdateParams{
 			Authority: c.consensusAuthority,
 			Block:     req.ConsensusParams.Block,
 			Evidence:  req.ConsensusParams.Evidence,

server/v2/stf/stf_router_test.go

@@ -8,7 +8,7 @@ import (
 	gogoproto "github.com/cosmos/gogoproto/proto"
 	gogotypes "github.com/cosmos/gogoproto/types"
 
-	"cosmossdk.io/core/appmodule/v2"
+	appmodulev2 "cosmossdk.io/core/appmodule/v2"
 	"cosmossdk.io/core/transaction"
 )
 
@@ -18,7 +18,7 @@ func TestRouter(t *testing.T) {
 
 	expectedResp := &gogotypes.StringValue{Value: "test"}
 
-	router := coreRouterImpl{handlers: map[string]appmodule.Handler{
+	router := coreRouterImpl{handlers: map[string]appmodulev2.Handler{
 		gogoproto.MessageName(expectedMsg): func(ctx context.Context, gotMsg transaction.Msg) (msgResp transaction.Msg, err error) {
 			if !reflect.DeepEqual(expectedMsg, gotMsg) {
 				t.Errorf("expected message: %v, got: %v", expectedMsg, gotMsg)

x/accounts/defaults/base/utils_test.go

@@ -8,7 +8,7 @@ import (
 
 	signingv1beta1 "cosmossdk.io/api/cosmos/tx/signing/v1beta1"
 	"cosmossdk.io/collections"
-	"cosmossdk.io/core/appmodule/v2"
+	appmodulev2 "cosmossdk.io/core/appmodule/v2"
 	"cosmossdk.io/core/event"
 	"cosmossdk.io/core/header"
 	"cosmossdk.io/core/store"
@@ -73,7 +73,7 @@ func makeMockDependencies(storeservice store.KVStoreService) accountstd.Dependen
 		SchemaBuilder:    sb,
 		AddressCodec:     addressCodec{},
 		LegacyStateCodec: mockStateCodec{},
-		Environment: appmodule.Environment{
+		Environment: appmodulev2.Environment{
 			EventService:  eventService{},
 			HeaderService: headerService{},
 		},

x/accounts/defaults/lockup/utils_test.go

@@ -9,7 +9,7 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"cosmossdk.io/collections"
-	"cosmossdk.io/core/appmodule/v2"
+	appmodulev2 "cosmossdk.io/core/appmodule/v2"
 	"cosmossdk.io/core/header"
 	"cosmossdk.io/core/store"
 	"cosmossdk.io/core/transaction"
@@ -114,7 +114,7 @@ func makeMockDependencies(storeservice store.KVStoreService) accountstd.Dependen
 		SchemaBuilder:    sb,
 		AddressCodec:     addressCodec{},
 		LegacyStateCodec: mockStateCodec{},
-		Environment: appmodule.Environment{
+		Environment: appmodulev2.Environment{
 			HeaderService: headerService{},
 		},
 	}