Skip to content

docs: sync example tutorials from cosmos/example#261

Open
evanorti wants to merge 1 commit intomainfrom
docs-sync/example-20260319-233641
Open

docs: sync example tutorials from cosmos/example#261
evanorti wants to merge 1 commit intomainfrom
docs-sync/example-20260319-233641

Conversation

@evanorti
Copy link
Contributor

Auto-synced from cosmos/example. Transforms docs/.md to sdk/next/tutorials/example/.mdx. Do not edit these files directly — edit the source in cosmos/example and let the sync bot update them.

@greptile-apps
Copy link

greptile-apps bot commented Mar 19, 2026

Greptile Summary

This PR adds a six-page tutorial series (00-overview through 05-run-and-test) auto-synced from cosmos/example, teaching developers how to build, wire, run, and test a Cosmos SDK chain using the x/counter module as a reference. The content is well-structured and covers the full module development lifecycle from proto definitions to simulation testing.

Three issues were identified:

  • Misleading zero-value query output (02-quickstart.mdx): The initial exampled query counter count output is shown as {} (proto3 JSON with zero fields omitted) while the same command after state is written shows YAML count: "5". The format inconsistency can confuse beginners into thinking the first query returned nothing.
  • Ineffective overflow guard (04-counter-walkthrough.mdx): The AddCount snippet shows if amount >= math.MaxUint64 as an overflow guard, but since amount is uint64 this condition is identical to amount == math.MaxUint64. It misses the real overflow scenario where count + amount wraps around with two large-but-not-maximal values. Teaching this pattern in a reference tutorial risks propagating the same bug into production modules.
  • Unreachable CLI example (05-run-and-test.mdx): The update-params command is listed with --from alice, but alice is not the governance module account. The transaction will always be rejected with ErrInvalidSigner, making the example non-functional as written.

Confidence Score: 3/5

  • Safe to merge after addressing the overflow guard and the misleading update-params example, which could teach incorrect patterns to SDK developers.
  • The majority of the content is accurate and well-written. Two issues stand out: the overflow guard in the walkthrough teaches a logically flawed safety pattern that could be copied into real modules, and the update-params CLI example will silently fail for readers who try it. Both are correctness issues in a tutorial intended as a reference implementation.
  • sdk/next/tutorials/example/04-counter-walkthrough.mdx (overflow guard) and sdk/next/tutorials/example/05-run-and-test.mdx (update-params authority).

Important Files Changed

Filename Overview
sdk/next/tutorials/example/00-overview.mdx New overview page introducing the tutorial series; content is accurate, internal links are consistent, and the branch descriptions match what is used throughout the series.
sdk/next/tutorials/example/01-prerequisites.mdx New prerequisites page covering Go, Make, Docker, Git installation and repo layout; instructions are clear and accurate with no identified issues.
sdk/next/tutorials/example/02-quickstart.mdx New quickstart page; the initial counter query output is shown as {} (JSON with zero-value omission) while the follow-up query uses YAML format count: "5", which is inconsistent and may confuse readers into thinking the zero-count query failed.
sdk/next/tutorials/example/03-build-a-module.mdx New step-by-step module building tutorial; proto definitions, keeper, MsgServer, QueryServer, module.go, AutoCLI, and app wiring steps are all well-structured and internally consistent.
sdk/next/tutorials/example/04-counter-walkthrough.mdx Full module walkthrough comparing minimal vs full counter; the AddCount overflow guard (if amount >= math.MaxUint64) is logically equivalent to amount == math.MaxUint64 for a uint64 and fails to catch the real integer overflow scenario, teaching an incorrect safety pattern.
sdk/next/tutorials/example/05-run-and-test.mdx Running and testing reference page; the update-params CLI example uses --from alice which will always fail with an authority error since Alice is not the governance module account, making the example misleading.

Last reviewed commit: "docs: sync example t..."

Comment on lines +49 to +55
You should see the following output, which means the counter is starting at `0`:


```text
{}
```

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Ambiguous zero-value output format

The initial query output is shown as {}, which is the JSON representation of an empty object (proto3 omits zero-value fields in JSON). However, the subsequent query output (after adding 5) uses YAML format: count: "5". This inconsistency is confusing for beginners — the reader may assume the command returned an empty or failed response rather than count: 0.

Consider either consistently using YAML for both outputs:

Suggested change
You should see the following output, which means the counter is starting at `0`:
```text
{}
```
You should see the following output, which means the counter is starting at `0`:
```yaml
count: "0"

Or add a short clarifying note explaining why the zero-value field is omitted in the initial output.

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

Comment on lines +226 to +229
func (k *Keeper) AddCount(ctx context.Context, sender string, amount uint64) (uint64, error) {
if amount >= math.MaxUint64 {
return 0, ErrNumTooLarge
}
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Ineffective overflow guard for uint64

The overflow check if amount >= math.MaxUint64 is logically equivalent to if amount == math.MaxUint64 because a uint64 value can never exceed math.MaxUint64. This means the check only blocks the single edge case of amount == 18446744073709551615 while entirely missing the real overflow risk: count + amount wrapping around when both values are large but neither is at the maximum individually.

For example, if count = 10 and amount = math.MaxUint64 - 5, the addition silently overflows to 4 without triggering this guard.

The correct check would be:

if amount > math.MaxUint64 - count {
    return 0, ErrNumTooLarge
}

Since this tutorial is meant to teach best practices for module development, presenting a flawed overflow guard as example code could mislead developers who copy this pattern into production modules.

Comment on lines +88 to +91

# Update module parameters (requires governance authority)
exampled tx counter update-params --from alice --chain-id demo --yes
```
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 update-params example will fail as shown

The comment acknowledges this requires governance authority, but the command uses --from alice. Alice is a regular funded test account, not the governance module account. Submitting this transaction from Alice will be rejected with ErrInvalidSigner at the module level because the authority check in MsgServer.UpdateParams compares msg.Authority against the governance module address (authtypes.NewModuleAddress(govtypes.ModuleName)).

This example should either:

  1. Be removed since it cannot be exercised in the quickstart environment, or
  2. Be replaced with a note explaining that params can only be updated via a governance proposal (exampled tx gov submit-proposal ...) rather than a direct transaction.

Showing a command that silently fails for non-obvious reasons may confuse readers debugging why their transaction always errors.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs-sync Automated docs sync PR

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant