Sdk api reference - #345
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
Greptile SummaryAdds generated Cosmos SDK gRPC, transaction, and REST API references for latest and next, together with generation, conformance, and release-gate tooling.
Confidence Score: 4/5The transaction release gate needs correction before merging because execution-time message failures can currently be reported as passing. The runner broadcasts in sync mode and treats CheckTx code zero as success without retrieving the delivered result, so governance and other state-dependent messages can fail in application execution while the release gate remains green; the remaining findings are non-blocking workflow-hardening and documentation issues. Files Needing Attention: scripts/api-reference/tx-onchain.py, scripts/api-reference/tx-coverage.toml, .github/workflows/sync-sdk-api-reference.yml, and the newly added documentation guides
|
| Filename | Overview |
|---|---|
| scripts/api-reference/tx-onchain.py | Adds exhaustive page-driven transaction coverage, but equates CheckTx acceptance with successful execution and does not probe skip entries. |
| scripts/api-reference/tx-coverage.toml | Defines prerequisites and expected outcomes, including governance dependencies that expose the runner’s inability to observe delivery failures. |
| scripts/api-reference/lib/openapi.js | Adds descriptor-driven response-schema correction with broad shape coverage; no present schema-repair failure was established. |
| .github/workflows/sync-sdk-api-reference.yml | Adds on-demand regeneration and PR creation, but invokes a mutable third-party action with repository-write permissions. |
| .claude/skills/release-version/SKILL.md | Documents the new release gate and ref override, while introducing punctuation prohibited by the repository writing standard. |
| docs.json | Adds latest and next API-reference navigation, including generated REST OpenAPI groups. |
Sequence Diagram
sequenceDiagram
participant Gate as Release gate
participant Runner as tx-onchain.py
participant Node as simd
participant App as SDK module
Gate->>Runner: Test documented message
Runner->>Node: broadcast --broadcast-mode sync
Node-->>Runner: CheckTx code 0
Runner->>Runner: Mark PASS
Node->>App: Deliver transaction later
App-->>Node: Execution failure
Note over Runner,App: Delivered failure is never fetched by the runner
Reviews (1): Last reviewed commit: "update" | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| sent = subprocess.run( | ||
| [simd, "tx", "broadcast", "/tmp/tx-onchain-signed.json", "--broadcast-mode", "sync", *common], | ||
| capture_output=True, text=True, | ||
| ) | ||
| output = sent.stdout + sent.stderr | ||
| code = re.search(r'"?code"?:\s*(\d+)', output) | ||
| raw = re.search(r'raw_log:\s*(.*)', output) | ||
| return (int(code.group(1)) if code else -1), (raw.group(1).strip()[:160] if raw else output.strip()[:160]) |
There was a problem hiding this comment.
When a transaction passes the ante handler but fails during module execution, --broadcast-mode sync returns code 0 and the runner marks it successful, causing invalid or state-dependent transaction examples to pass the release gate without successful delivery.
Knowledge Base Used: Cosmos SDK application and node platform
| if expect == "skip": | ||
| counts["skip"] += 1 | ||
| print(f" SKIP {name:52} {entry.get('note', '')[:60]}") | ||
| continue |
There was a problem hiding this comment.
The skip branch continues without broadcasting the filled message, although the manifest promises that skipped messages remain probed. A skip that becomes executable therefore stays green and silently omits a supported transaction from the release gate.
|
|
||
| Before committing to a freeze date, check how far the API reference has drifted from upstream without touching anything: | ||
|
|
||
| ```bash |
There was a problem hiding this comment.
This new guide uses em dashes despite the repository-wide writing rule prohibiting them, and the same pattern occurs throughout the added API-reference guidance, design document, and work log. Rewrite these instances with commas, periods, or separate sentences.
Context Used: CLAUDE.md (source)
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!
| - name: Open or update the PR | ||
| if: steps.summary.outputs.changed == 'true' | ||
| uses: peter-evans/create-pull-request@v6 | ||
| with: | ||
| token: ${{ secrets.GITHUB_TOKEN }} |
There was a problem hiding this comment.
If the mutable v6 tag is compromised or retargeted, the manually dispatched workflow runs the changed action code with contents and pull-request write permissions, enabling unauthorized repository changes. Pin the action to an immutable commit SHA.
How this was verified: The workflow grants contents and pull-request write permissions and passes that token directly to peter-evans/create-pull-request@v6.
1 participant
Summary
Adds a generated API reference for the Cosmos SDK covering gRPC query services, transaction messages, and REST gateway routes, plus the tooling that generates it and a release gate that executes every documented call against a chain built from the commit the pages record.
Changes
latestandnext, generated from upstream protos at a resolved commit. 122 query methods and 48 transaction messages.npm run release-check: one command that regenerates, runs the offline checks, buildssimdat that commit, starts a chain on isolated ports, and executes every documented query and transaction against it. Blocking gate before a freeze.--refon the generator, so a pre-freeze regeneration reads the release branch. Without it a freeze publishesmaincontent under the release's version number..claude/skills/release-version/SKILL.md, with a prose-review pass as the final step. No scheduled regeneration:sync-sdk-api-reference.ymlkeepsworkflow_dispatchonly.latest/. They instructgit checkout main, so a frozen copy documents code the reader is not running, andlatest/had sat two syncs behind. Both sync scripts refuse to run in the wrong direction, with tests.Review focus
lib/openapi.js, the response-schema repair. It changes how every schema in a 47,000 line published document is built, to fix two missing fields. Blast radius on current input is those two fields and nothing else, andtest/schema-repair.test.jspins the shapes per proto type, but the synthesis is general.Second,
tx-coverage.toml. Reading the delivered result reclassified 27 of 48 messages, and each now carries a manifest entry asserting why it cannot succeed. The gate passes because those entries are believed; a wrong one hides a real defect.Verification
Gate green from a clean tree: conformance 3023/3023; 122 queries plus 4 assertions with no findings; 48 messages as 11 success, 12 governance gated, 15 state-dependent, 1 skipped, 9 known gaps, each with a stated reason. 80 Node and 39 Python tests,
mint broken-linksclean. Detail inwork-log/sdk-api-reference.md.