plamentsv / cosmos-sdk-module-safety

Injectable Skill: Cosmos-SDK / CometBFT Module Safety

L1 trigger: L1_PATTERN=true AND COSMOS_SDK (cosmos-sdk / cometbft / tendermint / x/ modules detected)
Inject Into: depth-consensus-invariant, depth-state-trace
Language: Go (Cosmos-SDK)
Finding prefix: [COS-N]
Status: v0.1

Orchestrator Decomposition Guide

• Sections 1, 2, 6, 7: depth-consensus-invariant (determinism, ABCI-hook metering, ABCI panics, Msg routing — all chain-halt / safety class)
• Sections 3, 4, 5, 8: depth-state-trace (signer/state authority, module-account invariant, Dec rounding, fee/gas overflow — all accounting / authorization class)
• A single bug can span both lenses; record it once and cross-reference.

When This Skill Activates

Recon classifies the target as a Cosmos-SDK / CometBFT application chain or module set (go.mod requires cosmossdk.io/..., github.com/cosmos/cosmos-sdk, github.com/cometbft/cometbft, github.com/tendermint/tendermint, or the tree has x/<module>/keeper, x/<module>/types, abci.go, module.go). Cosmos app-chain bugs are predominantly consensus-halting (every validator must compute byte-identical state) and accounting (module accounts must reconcile) — both are in scope for Plamen L1 audits. Severity baseline is Medium; chain-halt / fork and fund-loss classes upgrade to High/Critical per docs/l1-mode/severity-matrix.md.

A Cosmos state-transition path is any code reachable from a Msg handler (msgServer methods), BeginBlock, EndBlock, InitGenesis, EndBlocker, PreBlocker, or an AnteHandler/PostHandler that mutates committed state. Everything in those paths runs on every validator and MUST be deterministic and panic-safe.

1. Non-Determinism in State-Transition Paths

Check: No state-transition path may depend on per-node, wall-clock, or unordered data. Two honest validators replaying the same block MUST compute the same app hash; any divergence forks or halts the chain.

Methodology:

1. From caller_map.md / function_summary.md, enumerate every function reachable from a Msg handler, BeginBlock(er), EndBlock(er), PreBlocker, InitGenesis, or Ante/Post handler. These are the consensus-critical set.

2. For each, grep / inspect for non-deterministic sources:

   • Map-range iteration without sort: for k := range <map> or for k, v := range <map> where iteration order affects writes, accumulation order, or emitted state. Go randomizes map iteration order per process. Fix pattern is a sorted key slice (maps.Keys + slices.Sort) before ranging. Flag any range-over-map in the consensus set that feeds a state write or running total.
   • Wall clock: time.Now(), time.Since(, time.Tick, os.Getenv — block time must come from ctx.BlockTime() / ctx.BlockHeader().Time, never the OS clock.
   • Randomness: math/rand, crypto/rand, rand.Intn, unseeded or per-node-seeded RNG in a handler.
   • Floating point: float32 / float64 arithmetic, math.Pow, math.Sqrt on consensus values — float results are not guaranteed bit-identical across platforms; use sdkmath.LegacyDec / big.Int.
   • unsafe., reflect-driven ordering, goroutines/channels whose completion order affects state, and select over multiple ready channels.
3. For each hit, confirm the value actually feeds committed state (app hash). A non-deterministic value used only for a log line is not a finding; one used for a balance, a winner selection, an iteration order over payouts, or an emitted event consumed by light clients is.

Tag: [COS-NONDET:{source}:{file}:{line}→{state-effect}]

2. Unmetered BeginBlock / EndBlock Hooks

Check: ABCI hooks (BeginBlock, EndBlock, BeginBlocker, EndBlocker, PreBlocker) run every block with no per-message gas meter bounding them. An unbounded or super-linear loop over state that an attacker can grow turns block production into a DoS / liveness failure.

Methodology:

1. Locate every BeginBlock(er) / EndBlock(er) / PreBlocker (grep func.*BeginBlock, func.*EndBlock, module.go, abci.go).

2. Inside each, walk loops. Flag:

   • Iteration over a GetAll* / IterateAll* / full-store iterator whose element count grows with user actions (e.g. all unbonding entries, all open orders, all proposals, all accounts) with no cap per block.
   • Nested loops over growing state (O(n²)) — e.g. for each validator, for each delegation.
   • len(slice) / iterator length driven by attacker-controlled creation (an attacker spams cheap objects; the hook then iterates all of them every block).
3. Confirm the absence of a per-block work cap (a maxPerBlock limit, a paginated queue drained N-at-a-time, or a time-bounded window). Absence with attacker-growable input is the finding.

Tag: [COS-ABCI-UNMETERED:{hook}:{file}:{line}:{growth-driver}]

3. GetSigners vs State-Modifying Field Mismatch

Check: A Msg may only mutate state owned by an account that is in its authenticated signer set. If a handler writes a field (owner, recipient, admin, target address) that is NOT derived from msg.GetSigners() (or the SDK-validated signer), an attacker can act on behalf of, or against, another account.

Methodology:

1. For each proto Msg type, find its GetSigners() (generated or hand-written) and record the signer-deriving field(s) (commonly Creator, Sender, FromAddress, Authority).
2. From state_write_map.md, list every field the corresponding msgServer handler writes or whose owner it changes.

3. Cross-check: every account/address the handler treats as authorized MUST be in the signer set. Flag when:

   • The handler reads an address from a message field NOT in GetSigners() and then debits/credits/reassigns it.
   • The handler trusts a stored object's owner without checking it equals a signer.
   • An Authority/governance gate is declared but the handler never compares the signer to it.
4. For x/authz-style delegated execution, verify the grant is checked for the exact Msg type and granter.

Tag: [COS-SIGNER-MISMATCH:{msg}:{written-field}:{file}:{line}]

4. Module-Account Bookkeeping Invariant

Check: For every module that holds funds, sum(per-user balances / deposits / shares tracked in module state) == bankKeeper.GetBalance(moduleAccount, denom) must hold after each block. Direct bank sends that bypass the module's own accounting break this silently.

Methodology:

1. Identify module accounts (authtypes.NewModuleAddress, GetModuleAccount, RegisterModuleAccount, permissions Minter/Burner/Staking).
2. Enumerate every credit/debit path: bankKeeper.SendCoinsFromAccountToModule, SendCoinsFromModuleToAccount, MintCoins, BurnCoins, and any direct bankKeeper.SendCoins(...) touching a module address.
3. Flag direct SendCoins / SendCoinsFromModuleToModule that move module funds WITHOUT a paired update to the module's internal ledger (the per-user mapping the module uses to compute who is owed what).
4. Verify (or recommend) a registered InvariantRoute (RegisterInvariants) asserting sum(internal) == moduleBalance. Absence of the invariant plus a bypassing send path is the finding.
5. Check mint/burn symmetry: every MintCoins that increases supply must have an accounting record; every BurnCoins must decrement the corresponding internal claim.

Tag: [COS-MODACCT-INVARIANT:{module}:{bypass-path}:{file}:{line}]

5. sdk.Dec / LegacyDec Rounding Non-Associativity

Check: sdkmath.LegacyDec (sdk.Dec) operations lose precision; the order of chained Quo/Mul changes the result, and rounding must always favor the protocol (never the user) to prevent dust extraction or under-collateralization.

Methodology:

1. Grep for chained decimal math: .Quo(, .Mul(, .QuoInt(, .MulInt(, .QuoTruncate(, .MulTruncate(, .RoundInt(, .TruncateInt(.
2. For each (a Quo b) Mul c (or Mul-then-Quo), check whether reordering changes the rounded result and whether the chosen order favors the user (e.g. rounding a withdrawal UP or a deposit-share DOWN). User-favorable rounding in a value-bearing path is a finding.
3. Verify rounding-direction consistency between paired operations: deposit→shares and shares→withdraw must round in protocol-favorable opposite directions so withdraw(deposit(x)) <= x.
4. Boundary-fuzz: substitute edge denoms (1 base unit, very large supply, dust amounts) and small exchange rates; precision loss is largest at extremes. Recommend a property test asserting the no-free-value invariant.

Tag: [COS-DEC-ROUNDING:{op-chain}:{file}:{line}:{who-favored}]

6. ABCI / Consensus-Path Panics

Check: A panic in DeliverTx (a Msg handler), BeginBlock, EndBlock, or PreBlocker is not a graceful tx failure — it can crash validators or, depending on recovery placement, cause inconsistent rollback and a chain halt. Handler errors must be returned as error, not raised as panic.

Methodology:

1. In the consensus set (Section 1 step 1), grep for panic(, .MustMarshal, Must*( helpers, unchecked array/slice indexing on message-controlled length, integer division by a message-controlled denominator, type assertions .(T) without the , ok form, and sdk.NewCoins(...)/coins.Add(...)/total.Add(...) over unsorted or unvalidated denoms (which panics on duplicate/invalid denom).
2. For each, trace whether the input can be attacker-controlled (a Msg field, a peer-supplied value, a genesis import). Attacker-reachable panic in a handler = at least a tx-griefing finding; in BeginBlock/EndBlock = liveness / chain-halt class.
3. Distinguish: panics in BeginBlock/EndBlock are the most severe (no per-tx recovery boundary). A panic recovered by the baseapp tx middleware that still corrupts a cached store before recovery is also a finding.
4. Verify ValidateBasic actually rejects the input class that would otherwise panic later (stateless validation is the correct place to bound lengths/denoms).

Tag: [COS-ABCI-PANIC:{path}:{panic-site}:{file}:{line}]

7. Missing / Unregistered Msg Handlers

Check: A proto Msg type with no route or no registered service handler silently fails (the tx is accepted into a block but the state change never happens, or it is rejected in a way that diverges from the spec). Every declared Msg* must be wired to exactly one handler.

Methodology:

1. Enumerate every Msg* RPC from the proto / tx.pb.go MsgServer interface (and any legacy sdk.Msg types).
2. Cross-check registration: RegisterMsgServer / _Msg_serviceDesc, RegisterServices, legacy NewHandler switch arms, and RegisterLegacyAminoCodec / RegisterInterfaces for the concrete type.
3. Flag any Msg* with no msgServer method, no route arm, or unregistered concrete type → the message is unhandled / un-decodable.
4. Also flag the inverse mismatch: a handler that exists but whose Msg type is not registered in the interface registry (decoding fails) — and duplicate routes (two arms for one type).

Tag: [COS-MSG-UNROUTED:{msg-type}:{registration-gap}]

8. Fee / Gas uint64 Overflow

Check: Fee and gas arithmetic on uint64 (baseFee * gasUsed, refund computations, gas-price multiplication) can overflow and wrap, producing a near-zero fee, a refund larger than the escrowed amount, or an out-of-bounds gas grant.

Methodology:

1. Grep for uint64 multiplication/addition in fee/gas paths: GasUsed, GasWanted, gasPrice, baseFee, Fee.Amount, AnteHandler fee deduction, refund/ConsumeGas accounting.
2. For each a * b / a + b on uint64 where either operand is message- or block-controlled, check for an overflow guard (use of sdkmath.Int / big.Int, or an explicit math.MaxUint64 / b pre-check).
3. Verify refund <= escrowed: a refund computed by subtraction must guard against underflow (refund > paid).
4. Recommend migrating value-bearing fee/gas math to sdkmath.Int (arbitrary precision) rather than raw uint64.

Tag: [COS-FEE-OVERFLOW:{op}:{file}:{line}]

Bounded Reads

MANDATORY — do not bulk-read large source files (context-collapse risk). Drive analysis from the Go SCIP bake graph artifacts first, then open individual symbols on demand:

• Read caller_map.md, callee_map.md, state_write_map.md, and function_summary.md (produced by the Go SCIP bake) to build the consensus-critical reachability set and the per-field writer set without reading whole modules.
• Open an individual source symbol (one function / one keeper method) ON-DEMAND only when a graph artifact flags it — never read an entire x/<module> tree or a multi-thousand-line file in one go.
• If a needed symbol is not in the graph artifacts, grep for the specific function/identifier and read only the matched span plus a few lines of context.
• Write enumerations (consensus set, signer map, module-account paths) to small scratchpad notes; do not hold whole files in context.

Output schema

• Layer: consensus (Sections 1, 2, 6, 7) / state (Sections 3, 4, 5, 8)
• Bug class: non-determinism / unmetered-abci / signer-mismatch / module-account-invariant / dec-rounding / abci-panic / msg-unrouted / fee-overflow
• Finding prefix: [COS-N]
• Preferred evidence tags: [FUZZ-PASS] (proptest/Go fuzz on the handler or Dec math) > [NON-DET-PASS] (replay differential showing divergent app hash) > [CODE-TRACE]
• Severity baseline: Medium; upgrade to High/Critical for chain-halt / fork (Sections 1, 2, 6) or fund loss (Sections 4, 5, 8); see docs/l1-mode/severity-matrix.md

Known bug exemplars

Illustrative bug CLASSES only — methodology finds these generically, the names are public-incident exemplars, not protocol targets.

1. Go map-iteration non-determinism class — ranging over a Go map in a handler / BeginBlock and using iteration order to write state or accumulate a total. Because Go randomizes map order per process, validators diverge → app-hash mismatch → chain halt. Multiple Cosmos chains have shipped and patched this class. Catch point: Section 1 map-range check.
2. ICS-23 / Merkle proof-gap class (Dragonberry-class) — a missing or malformed membership/non-membership proof check lets a forged value pass verification. (Cross-chain proof verification primarily lives in the light-client-proof-verification skill; this skill flags the Cosmos-side Msg/keeper entry points that consume such proofs and the signer/authority gating around them.) Catch point: Sections 3 and 6 (entry-point authority + panic-safety on proof inputs).
3. Module-account drain class — a keeper that pays out via direct bankKeeper.SendCoins from the module account without decrementing the per-user ledger, so sum(internal) > moduleBalance and later claimants are bricked, or the inverse over-issuance. Catch point: Section 4.
4. Unmetered EndBlock loop class — iterating all of an attacker-growable collection (open orders, unbonding queue) every block with no cap, so cheap spam linearly inflates block time. Catch point: Section 2.
5. AnteHandler fee-overflow class — gasPrice * gasWanted overflowing uint64 to a tiny fee, defeating fee-market DoS protection. Catch point: Section 8.

Fallback

If the SCIP graph artifacts are unavailable or incomplete:

• List x/*/keeper/*.go, x/*/abci.go, x/*/module.go, and app/app.go.
• Grep for func.*BeginBlock, func.*EndBlock, func.*PreBlocker (consensus hooks).
• Grep for .* := range and intersect with handler/hook files (non-determinism candidates).
• Grep GetSigners, SendCoins, MintCoins, BurnCoins, panic(, .Quo(, .Mul(, RegisterMsgServer, RegisterServices.
• Read proto/**/tx.proto for the full Msg service to enumerate handlers for Section 7.

Cross-references

• Related: consensus-safety-invariants (general non-determinism / state-transition completeness), go-concurrency-safety (Go map / goroutine hazards), light-client-proof-verification (ICS-23 / Merkle proof soundness), validator-lifecycle-and-slashing (x/staking, x/slashing lifecycle), dependency-audit-nodeclient (cosmos-sdk / cometbft version CVEs).
• Consumed by: depth-consensus-invariant, depth-state-trace
• Severity: docs/l1-mode/severity-matrix.md