If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/cosmos/cosmos-sdk shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 12 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 62% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live cosmos/cosmos-sdk repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/cosmos/cosmos-sdk.

What it runs against: a local clone of cosmos/cosmos-sdk — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in cosmos/cosmos-sdk | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of cosmos/cosmos-sdk. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/cosmos/cosmos-sdk.git
#   cd cosmos-sdk
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of cosmos/cosmos-sdk and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "cosmos/cosmos-sdk(\\.git)?\\b" \\
  && ok "origin remote is cosmos/cosmos-sdk" \\
  || miss "origin remote is not cosmos/cosmos-sdk (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f "api/cosmos/app/v1alpha1/config.pulsar.go" \\
  && ok "api/cosmos/app/v1alpha1/config.pulsar.go" \\
  || miss "missing critical file: api/cosmos/app/v1alpha1/config.pulsar.go"
test -f ".github/workflows/proto.yml" \\
  && ok ".github/workflows/proto.yml" \\
  || miss "missing critical file: .github/workflows/proto.yml"
test -f ".golangci.yml" \\
  && ok ".golangci.yml" \\
  || miss "missing critical file: .golangci.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/cosmos/cosmos-sdk"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Cosmos SDK is a modular Go framework for building application-specific blockchains (Layer 1 chains) with native interoperability via IBC (Inter-Blockchain Communication Protocol). It provides pre-built modules for state management, governance, permissioning, and tokenization, allowing developers to compose custom blockchains without rebuilding consensus or networking layers. Monorepo structure: api/ contains protobuf definitions (api/cosmos/app/runtime, etc.), .github/workflows/ has 25+ CI/CD pipelines for testing, linting, proto generation, and nightly builds. Core modules live in sibling directories (inferred from 'MODULES' in README). Makefile drives local development. C/Assembly files (~695KB) suggest cryptographic primitives or consensus layer integration.

Blockchain developers and chain teams building sovereign application-specific chains who need composable, customizable blockchain infrastructure. Contributors range from Cosmos ecosystem maintainers to external developers extending modules for specific use cases (200+ production chains already use it).

Production-ready and actively maintained. The codebase is substantial (~10.7MB Go code), has mature CI/CD setup (25+ GitHub workflows in .github/workflows/), comprehensive testing infrastructure (test.yml, sims workflows), and uses semantic versioning. However, the README explicitly warns 'we are still making some breaking changes,' indicating ongoing refinement despite stability.

Low-to-moderate risk for stable use, higher for bleeding-edge features. Dependencies include protobuf code generation (proto.yml workflow), gogoproto v1.7.2, and tight coupling to CometBFT consensus. The modular architecture means breaking changes in core modules can impact downstream chains. Requires Go 1.25+ (modern constraint). Security policy exists (SECURITY.md) suggesting active vulnerability response.

Active development on proto-based code generation (proto.yml, proto-docker.yml, proto-registry.yml workflows), nightly simulation testing (sims-nightly.yml, sims-054.yml), system-level integration tests (systemtests.yml), and dependency management (dependabot.yml, pr-go-mod-tidy-mocks.yml). Documentation building is automated (build-docs.yml). PR labeling and changelog enforcement suggest mature governance.

git clone https://github.com/cosmos/cosmos-sdk.git && cd cosmos-sdk && go mod download && make install. Requires Go 1.25+ installed locally. The Makefile orchestrates build, test, and simulation targets.

Daily commands: make test (unit tests), make test-sim-nondeterminism (determinism checks), make install (build CLI), or make build-docs (generate documentation). See .github/workflows/test.yml for full test matrix. Nightly builds use build-simd-nightlies.yml for integration testing.

• go.mod — Root module definition; all dependencies and Go version constraints cascade from here—essential for understanding build compatibility and external package versions.
• Makefile — Standard build, test, and proto-generation entry point; contributors must understand the build pipeline and how protobuf compilation integrates.
• api/cosmos/app/v1alpha1/config.pulsar.go — Core app configuration proto-generated code; defines the module system and runtime configuration that all Cosmos SDK chains inherit.
• .github/workflows/proto.yml — Proto code generation CI/CD pipeline; ensures proto files stay in sync with generated Go code—critical for contributors modifying APIs.
• .golangci.yml — Linting rules and code quality standards; all contributions must pass these checks, so understanding the style guide is mandatory.
• README.md — High-level overview of the Cosmos SDK framework, its use cases, and ecosystem context—essential onboarding document.
• UPGRADING.md — Breaking changes and migration guide between versions; critical reference for understanding API stability and backwards compatibility guarantees.

Add a New gRPC Query Endpoint to an Existing Module

1. Define the new query message in the module's proto file (e.g., api/cosmos/mymodule/v1beta1/query.proto). Add a new message QueryNewThingRequest {} and message QueryNewThingResponse {}. (api/cosmos/mymodule/v1beta1/query.proto)
2. Extend the Query service in the same proto file with a new RPC method: rpc QueryNewThing(QueryNewThingRequest) returns (QueryNewThingResponse) {}. (api/cosmos/mymodule/v1beta1/query.proto)
3. Run make proto-gen (defined in Makefile) to regenerate query_grpc.pb.go and query.pulsar.go files. (Makefile)
4. Implement the handler in the module's keeper code (in the main SDK repo, not in api/) following the generated service interface. (Makefile)

Add a New Transaction Type to a Module

1. Define the new message in the module's proto file (e.g., api/cosmos/mymodule/v1beta1/tx.proto). Add message MsgDoSomething {} with required fields. (api/cosmos/mymodule/v1beta1/tx.proto)
2. Add the new Msg to the Msg service in the same proto file: rpc DoSomething(MsgDoSomething) returns (MsgDoSomethingResponse) {}. (api/cosmos/mymodule/v1beta1/tx.proto)
3. Run make proto-gen to regenerate tx_grpc.pb.go and tx.pulsar.go. (Makefile)
4. Implement the handler in the module's keeper and register it with the Msg router. (Makefile)

Add a New Module Config to the App Dependency Graph

1. Define module metadata in a proto file under api/cosmos/mymodule/module/v1/module.proto, specifying dependencies and configuration options. (api/cosmos/auth/module/v1/module.proto)
2. Run make proto-gen to generate the module config proto files. (Makefile)
3. In the main SDK codebase, register the module's AppModule with the app's module manager and update api/cosmos/app/v1alpha1/config.proto if adding new module config fields. (api/cosmos/app/v1alpha1/config.pulsar.go)
4. Test that the module initializes correctly by running integration tests. (.github/workflows/test.yml)

Update Proto Definitions and Keep Generated Code in Sync

1. Modify any .proto file under api/cosmos/*/ to add new fields, messages, or services. (api/cosmos/auth/v1beta1/auth.proto)
2. Run make proto-gen locally to regenerate all .pulsar.go and *_grpc.pb.go files. (Makefile)
3. Commit both the .proto changes and the regenerated .go files together. (.github/workflows/proto.yml)
4. The CI pipeline (proto.yml) will verify that generated code is in sync; if it fails, re-run make proto-gen and commit the fixes. (.github/workflows/proto.yml)

• Protocol Buffers (protobuf) + gRPC — Language-agnostic, efficient serialization for blockchain state and RPC; enables multi-language client libraries and future-proof API evolution.
• Go — High performance, strong concurrency primitives for validator consensus and transaction processing; excellent standard library for networking and cryptography.
• Modular architecture (AppModule pattern) — Allows developers to compose custom blockchains by selecting and ordering modules; reduces code duplication across 200+ production chains.
• Dependency injection (app/runtime) — Decouples module initialization from business logic; enables dynamic module composition at startup without tight coupling.

• Proto-first API design (api/ directory separate from implementation)

  • Why: Proto files are the source of truth for the wire format and contract; enables SDK maintainers to evolve implementation independently of clients.
  • Consequence: Adds regeneration overhead—must always keep proto and Go code in sync; CI enforces this. Requires discipline but prevents API drift.

• Pulsar proto codegen (vs. legacy protoc Go plugin)

  • Why: Pulsar generates more ergonomic, zero-copy APIs and better message reflection support.
  • Consequence: Newer integration path; some older chains may still use gogoproto. Requires updating proto generation toolchain.

• Monorepo structure with 600+ files

  • Why: Single source of truth for all core modules and shared types; easier to coordinate breaking changes across auth, bank, authz, etc.
  • Consequence: Large repo to clone and test; longer CI times. Mitigated by careful go.mod and modular test targets.

• Does not implement consensus algorithms directly—delegates to Tendermint/CometBFT.
• Does not provide a UI framework or wallet implementation—only backend blockchain engine and gRPC APIs.
• Does not handle cross-chain message passing (IBC is a separate module, not core SDK

Proto compilation requires running the proto.yml workflow or local protoc invocation; out-of-sync generated code causes silent bugs. Breaking changes documented in CHANGELOG.md/UPGRADING.md are frequent—always check when upgrading. CometBFT version pinning: SDK releases are tightly coupled to specific CometBFT versions (see dependencies). IBC module is a separate module (ibc-go), not in this repo. Amino codec is legacy but still partially supported (api/amino/)—avoid for new code. Simulation tests are slow and non-flaky validation requires determinism; nightly runs can fail on transient env issues.

• Application-Specific Blockchain (AppChain) — Core value prop of SDK: unlike Ethereum's smart contract model, Cosmos SDK lets each chain define its own state, modules, and rules; essential for understanding why SDK exists.
• Inter-Blockchain Communication (IBC) Protocol — Native interop between chains; SDK integrates IBC natively (ibc-go module), enabling cross-chain state verification without wrapped bridges.
• Protobuf Code Generation & Amino Encoding — SDK uses protobuf + gogoproto for serialization; understanding proto compilation (proto.yml workflow) and legacy Amino codec is critical for extending types.
• Modular Blockchain Architecture (Module System) — SDK allows plugging pre-built modules (auth, staking, governance) or custom modules; architecting module dependencies and state is core to using the SDK.
• Byzantine Fault Tolerant (BFT) Consensus — CometBFT provides BFT consensus; SDK is consensus-agnostic but optimized for BFT. Simulation tests (sims.yml) validate determinism, a BFT requirement.
• State Machine Replication (SMR) — Blockchains are deterministic state machines; SDK's architecture enforces this (sims check non-determinism). Signatures, ordering, and determinism all hinge on SMR.
• Governance Module & On-Chain Upgrades — SDK ships with a governance module for proposal voting and chain upgrades without forking; critical for production chain operations mentioned in module docs.

• cometbft/cometbft — Consensus engine recommended and tightly integrated with SDK; Cosmos chains default to CometBFT for BFT consensus.
• cosmos/ibc-go — Inter-blockchain communication protocol implementation; SDK docs mention 'native integration with IBC' but ibc-go is a separate module.
• cosmos/cosmos-proto — Protobuf code generation tools and standards (referenced in go.mod); defines proto conventions for Cosmos SDK.
• cosmos/gaia — Reference implementation of a Cosmos SDK chain; production example for understanding module composition and deployment.
• cosmos/gov-workshop — Companion tutorial/workshop repo; SDK docs point to 'Cosmos SDK Tutorials' for hands-on learning.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for proto-registry workflow and generated code validation

The repo has a .github/workflows/proto-registry.yml workflow but lacks visible integration tests that validate proto-generated code consistency across the api/ directory. With extensive pulsar.go files across api/cosmos/* modules, adding tests to verify generated protobuf code matches proto definitions and detects breaking changes would prevent silent proto regressions.

• [ ] Create tests/integration/proto_validation_test.go to validate api/cosmos//v1beta1/.pulsar.go matches source .proto files
• [ ] Add checksum/hash validation for generated code in CI using proto-registry workflow
• [ ] Create documentation in docs/ explaining proto code generation requirements and validation process
• [ ] Reference specific modules like api/cosmos/auth/v1beta1/, api/cosmos/authz/ to ensure consistency

Add GitHub Action workflow for API backward compatibility checking on pull requests

The api/ directory contains versioned protobuf definitions (v1beta1, v1alpha1) but there's no automated CI check to detect breaking API changes. Given the critical nature of blockchain APIs, a workflow to detect removed/renamed fields, changed message signatures across api/cosmos//.pulsar.go would prevent accidental breaking changes.

• [ ] Create .github/workflows/api-compatibility-check.yml that runs buf breaking on proto files
• [ ] Configure the workflow to compare api/cosmos/ against main branch to detect proto breaking changes
• [ ] Add protobuf API diffing tool (buf or similar) to catch signature mismatches in generated files
• [ ] Document breaking change policy in UPGRADING.md with specific examples from existing v1alpha1 to v1beta1 migrations

Add missing dependency security audit workflow for transitive Go module vulnerabilities

While dependencies-review.yml exists, the go.mod specifies golang.org/x and google.golang.org packages with indirect dependencies that could have vulnerabilities. A dedicated security audit using nancy, trivy, or similar tools running on the full dependency tree (particularly google.golang.org/grpc v1.78.0 and google.golang.org/protobuf v1.36.11) would catch supply chain risks before release.

• [ ] Create .github/workflows/security-audit.yml running 'nancy check' or 'go install github.com/sonatype-nexus-community/nancy@latest' against go.mod
• [ ] Add trivy scanning for container images in Dockerfile and nightlies workflows
• [ ] Document security scanning results and process in SECURITY.md with remediation steps
• [ ] Integrate with existing dependabot.yml configuration to create issues for vulnerable dependencies

• Add missing unit tests for api/cosmos/app/runtime proto types; many .proto files lack corresponding *_test.go coverage in the Go SDK layer.
• Enhance markdown documentation linting in .github/workflows/lint.yml to catch broken internal doc links (currently md-link-checker.yml exists but may not cover all docs/).
• Create a minimal example application in examples/ that demonstrates module composition and IBC setup; README mentions tutorials but repo structure doesn't show a runnable reference app.

The Cosmos SDK repository demonstrates good security practices with a dedicated security policy, HackerOne bug bounty program, and Dependabot automation. However, there are concerns with the Dockerfile's use of potentially unreleased Go versions, lack of privilege dropping, and incomplete security hardening. The codebase lacks visible hardcoded secrets and obvious injection vulnerabilities in the analyzed files. Dependency management is generally sound with pinned versions, though pseudo-versioned indirect dependencies warrant monitoring. The large gRPC API surface requires careful endpoint validation. Overall security posture is moderate-to-good but requires attention to infrastructure hardening and continuous dependency monitoring.

• Medium · Outdated Go Version in Dockerfile — Dockerfile (line: FROM golang:1.25-alpine AS build-env). The Dockerfile specifies Go 1.25-alpine, which may not be a released stable version. Using unreleased or bleeding-edge versions can expose the build to untested compiler bugs and security issues. The go.mod file specifies 'go 1.25.0' which aligns with this, but this version may not exist or be officially released. Fix: Use a stable, released Go version (e.g., 1.23.x or latest stable LTS). Verify that go 1.25.0 is an official release before using it in production builds.
• Medium · Missing Security Headers in Dockerfile — Dockerfile. The Dockerfile lacks security best practices such as: (1) No USER directive to drop privileges, (2) No HEALTHCHECK, (3) No vulnerability scanning, (4) No image signature verification. The image runs with default root privileges. Fix: Add 'USER' directive to run as non-root user, implement HEALTHCHECK, use multi-stage builds to minimize attack surface, and implement image scanning in CI/CD pipeline.
• Low · Incomplete Dockerfile Optimization Comment — Dockerfile (line: # optimization:). The Dockerfile contains an incomplete optimization comment ('# optimization:') with no actual optimization code following it, suggesting incomplete documentation or cleanup. Fix: Either complete the optimization comment with actual implementation or remove it. Ensure all comments accurately reflect the code.
• Low · Dependency Version Pinning Precision — go.mod (indirect dependencies in googleapis). While go.mod uses specific versions for direct dependencies, some indirect dependencies use date-based versions (e.g., 'v0.0.0-20260114163908-3f89685c29c3'). This pseudo-versioning makes it harder to track exact security patches and can lead to supply chain risks. Fix: Regularly audit and update dependencies. Consider using 'go get -u' with caution, and implement automated dependency scanning (e.g., Dependabot, which is already configured in the repo).
• Low · Verbose gRPC/Protobuf API Surface — api/ directory structure. The extensive api/ directory structure with generated .pulsar.go and _grpc.pb.go files indicates a large gRPC API surface. While this is intentional for a blockchain framework, it increases the attack surface area and requires careful validation of all exposed endpoints. Fix: Implement strict input validation and rate limiting on all gRPC endpoints. Conduct regular security audits of the API surface. Use gRPC interceptors for authentication and authorization.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.