Skip to content

docs: enhance proto/buf.md with comprehensive API documentation #25444

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

docs: enhance proto/buf.md with comprehensive API documentation #25444

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 48 additions & 2 deletions proto/buf.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,49 @@
# Protobufs
# Cosmos SDK Protocol Buffers

This is the public protocol buffers API for the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk).
This directory contains the public protocol buffers API definitions for the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk). These protobuf files define the core data structures, services, and APIs used across all Cosmos SDK modules.

## Overview

The Cosmos SDK uses Protocol Buffers extensively for:
- **Message definitions** - Transaction messages and query requests/responses
- **Service definitions** - gRPC services for queries and transactions
- **Type definitions** - Core data structures like accounts, coins, and governance
- **API contracts** - Standardized interfaces between modules and clients

## Structure

```
proto/
├── cosmos/ # Core Cosmos SDK modules (auth, bank, gov, etc.)
├── tendermint/ # CometBFT/Tendermint types
├── amino/ # Amino encoding definitions
└── buf.*.yaml # Buf configuration files
```

## Key Components

### Core Modules (`cosmos/`)
- **`auth/`** - Account authentication and transaction signing
- **`bank/`** - Token transfers and balance management
- **`gov/`** - On-chain governance and voting
- **`staking/`** - Proof-of-stake validator management
- **`distribution/`** - Fee and reward distribution
- **`slashing/`** - Validator penalty mechanisms
- **`mint/`** - Token minting and inflation
- **`upgrade/`** - Software upgrade coordination

### Generation Targets
- **Go code** - Generated using gogoproto and pulsar generators
- **Swagger docs** - REST API documentation
- **gRPC services** - Service definitions for queries and transactions

## Usage

These protobuf files are published to [buf.build/cosmos/cosmos-sdk](https://buf.build/cosmos/cosmos-sdk) and can be imported by other projects:

```yaml
deps:
- buf.build/cosmos/cosmos-sdk
```

For detailed usage instructions, see the [protobuf documentation](https://docs.cosmos.network/main/build/tooling/protobuf).