Skip to content

docs: write the effective-gno roadmap as short tips - #6000

Open
davd-gzl wants to merge 38 commits into
gnolang:masterfrom
davd-gzl:docs/effective-gno-roadmap
Open

davd-gzl wants to merge 38 commits into
gnolang:masterfrom
davd-gzl:docs/effective-gno-roadmap

Conversation

@davd-gzl

@davd-gzl davd-gzl commented Jul 22, 2026 •

Copy link
Copy Markdown
Member

Part of #5031

Effective Gno ended on a TODO listing topics nobody wrote, and five links on four pages pointed at a storage section, #choose-storage-types-by-access-pattern, that acd01fa deleted.

This writes those topics as short tips, each a few lines and a link to the page that covers it, and cuts the older sections to the same shape: 5631 words on master, 1959 here. The storage section returns under its old anchor.

The testing helpers that call a realm as another user or contract move to a new section of gno-testing.md.

Coins, GRC20 tokens and how a realm takes a Coin payment move to a new page, coins-and-tokens.md, since they define the assets rather than a practice. The links to the payment section, in AGENTS.md, the security guide, gno-ai-contract-review.md and three realm comments, follow it. The payment check reads unsafe.OriginSend(), so the rule in AGENTS.md and the security guide that deleted every chain/runtime/unsafe import beside a cur realm parameter now deletes only one that PreviousRealm() alone uses.

@Gno2D2

Gno2D2 commented Jul 22, 2026 •

Copy link
Copy Markdown
Collaborator

🛠 PR Checks Summary

All Automated Checks passed. ✅

Manual Checks (for Reviewers):
  • IGNORE the bot requirements for this PR (force green CI check)
Read More

🤖 This bot helps streamline PR reviews by verifying automated checks and providing guidance for contributors and reviewers.

✅ Automated Checks (for Contributors):

🟢 Maintainers must be able to edit this pull request (more info)
🟢 Pending initial approval by a review team member, or review from tech-staff

☑️ Contributor Actions:
  1. Fix any issues flagged by automated checks.
  2. Follow the Contributor Checklist to ensure your PR is ready for review.
    • Add new tests, or document why they are unnecessary.
    • Provide clear examples/screenshots, if necessary.
    • Update documentation, if required.
    • Ensure no breaking changes, or include BREAKING CHANGE notes.
    • Link related issues/PRs, where applicable.
☑️ Reviewer Actions:
  1. Complete manual checks for the PR, including the guidelines and additional checks if applicable.
📚 Resources:
Debug
Automated Checks
Maintainers must be able to edit this pull request (more info)

If

🟢 Condition met
└── 🟢 And
    ├── 🟢 The base branch matches this pattern: ^master$
    └── 🟢 The pull request was created from a fork (head branch repo: davd-gzl/gno)

Then

🟢 Requirement satisfied
└── 🟢 Maintainer can modify this pull request

Pending initial approval by a review team member, or review from tech-staff

If

🟢 Condition met
└── 🟢 And
    ├── 🟢 The base branch matches this pattern: ^master$
    └── 🟢 Not (🔴 Pull request author is a member of the team: tech-staff)

Then

🟢 Requirement satisfied
└── 🟢 If
    ├── 🟢 Condition
    │   └── 🟢 Or
    │       ├── 🔴 At least one of these user(s) reviewed the pull request: [aronpark1007 davd-gzl jefft0 notJoon omarsy MikaelVallenet] (with state "APPROVED")
    │       ├── 🟢 At least 1 user(s) of the team tech-staff reviewed pull request
    │       └── 🔴 This pull request is a draft
    └── 🟢 Then
        └── 🟢 Not (🔴 This label is applied to pull request: review/triage-pending)

Manual Checks
**IGNORE** the bot requirements for this PR (force green CI check)

If

🟢 Condition met
└── 🟢 On every pull request

Can be checked by

  • Any user with comment edit permission

@davd-gzl
davd-gzl marked this pull request as ready for review July 24, 2026 22:04
@Gno2D2 Gno2D2 added the review/triage-pending PRs opened by external contributors that are waiting for the 1st review label Jul 24, 2026
@davd-gzl
davd-gzl requested a review from alexiscolin August 5, 2026 08:31

@moul moul left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

blocking until #5835 is merged.

Master's only change to effective-gno.md since the fork is 24 lines: the
GetCoin note in the Coins section, and the Foo Token example turning
UserTeller into an unexported userTeller with a Transfer wrapper. Both are
carried onto this branch's rewrite. MyBalance keeps this branch's
cur.Previous() and takes master's Token.BalanceOf, since UserTeller is gone.
@Gno2D2 Gno2D2 removed the review/triage-pending PRs opened by external contributors that are waiting for the 1st review label Sep 1, 2026
One conflict, in docs/resources/effective-gno.md. This branch replaces the
sections master still carries below "Define types and interfaces in pure
packages", so the resolution keeps the branch side of that region.

Master moved the grc20 package from p/demo/tokens/grc20 to p/nt/grc20/v0 and
fixed both references. One of them sits inside the conflict region here and
one outside, so the outside fix merged and the inside one had to be carried
over by hand: the branch had moved that import into the Coins section.
…ction samples

Nine samples opened on

    if !cur.IsCurrent() {
        panic("spoofed realm")
    }

before reading cur.Previous().Address(). Every entry from another realm mints
a fresh cur, so the guard refuses nobody and the panic message names something
that cannot happen. The live check is on a realm value the caller hands over
as an ordinary parameter, which none of these samples takes.

The paragraph on chain/runtime/unsafe said nothing verifies a stack walk the
way a cur handle is verified. It now contrasts the two on what is true: a
stack walker answers from wherever it stands, and the runtime binds cur to the
frame that received it.

@alexiscolin alexiscolin left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thanks for picking up the roadmap! I left notes inline: the callback section needs a rewrite (it's a security point), and a few numbers and paths are off.

More generally, following #5651, I'd cut each new tip down to a few lines plus a link. Many of the sections repeat pages we already have (gno-data-structures.md, community-packages.md, gas-fees.md, the security guide). The app patterns (state machine, subscription, governance) would fit better as r/docs examples. Putting the section reorder in its own commit would also make the diff much easier to review.

Comment thread docs/resources/effective-gno.md Resolved
Comment thread docs/resources/effective-gno.md Resolved
Comment thread docs/resources/effective-gno.md Resolved
Comment thread docs/resources/effective-gno.md Resolved
Comment thread docs/resources/effective-gno.md Resolved
Comment thread docs/resources/effective-gno.md Resolved
Comment thread docs/resources/effective-gno.md Resolved
Comment thread docs/resources/effective-gno.md Resolved
Comment thread docs/resources/effective-gno.md Resolved
…ink payments and restricted_denoms, simplify package naming
@github-actions github-actions Bot added 🧾 package/realm Tag used for new Realms or Packages. 📄 top-level-md labels Oct 11, 2026
@davd-gzl
davd-gzl marked this pull request as ready for review October 11, 2026 16:44
@davd-gzl

davd-gzl commented Oct 11, 2026 •

Copy link
Copy Markdown
Member Author

@alexiscolin, since your review at b610600:

  • Each tip is now a few lines and a link to the page that covers it, in master's section order. The page goes from 5631 words on master to 1959.
  • Your notes: the callback tip states the security guide's rule and links §5.3. The frame-stack paragraph, the gas tip and the authz section are gone, and the stale gas line in gas-fees.md is fixed in docs: correct transaction fees, receipts, and stale references #6099. The forking tip uses uint256 as you suggested, and the versioning example is cut.
  • Master's introduction and the lead under "Counter-intuitive good practices" are back.
  • Coins, GRC20 tokens, wrapping and the Coin payment check move to a new page, coins-and-tokens.md, which opens on when to pick each. The links to the payment section in AGENTS.md, the security guide and three realm comments follow it.
  • The testing helpers that call a realm as another user or contract move to a new section of gno-testing.md, and the attacker-testing tip links it.
  • Package naming, file layout and versioning are one section, opening on a file tree. Paths read p/{namespace}/{name}.
  • A maketx run tip is added, and the body now closes [docs] Effective gno documentation roadmap #5031.
  • Smaller edits: restricted_denoms links the realm that sets it, gnorkle reads as one approach among others, and the GetCoin tip is removed.

b610600..c77b64f

@davd-gzl
davd-gzl requested a review from alexiscolin October 11, 2026 16:46

@alexiscolin alexiscolin left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

(Review done with AI help.)

Thanks David, this reads much better, and my inline notes are all addressed. What's left: the payment check on the new coins page and the teller comment (inline), and two "see also" lines outside the diff that still say effective-gno.md covers payment guards, docs/resources/gno-security-guide.md:613 and docs/resources/gno-ai-contract-review.md:261. Could they point to coins-and-tokens.md now? The app patterns didn't make it to r/docs, so could you switch to "Part of #5031" or open a follow-up issue, so they don't get lost when this closes?

Comment thread docs/resources/coins-and-tokens.md Outdated
`maketx call` with `-send`.
In the called function, first check that the user called you directly with
`cur.Previous().IsUserCall()`, then read the amount sent with
[`unsafe.OriginSend()`](./gno-stdlibs.md#originsend). The

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

The move dropped master's sample and the amount comparison: this now just says to "read" OriginSend(), and §5.5 links straight back here. Someone following it literally checks IsUserCall() and never compares what was paid. Could you keep a short sample here, IsUserCall() plus if unsafe.OriginSend().AmountOf("ugnot") != price { panic(...) }?

@davd-gzl davd-gzl Oct 21, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Fixed: c47b9df, the section shows a Buy sample with both checks again, and says that without the amount check a call attaching no coins succeeds.

Comment thread docs/resources/coins-and-tokens.md Outdated
var (
Token *grc20.Token
privateLedger *grc20.PrivateLedger
// Unexported: whoever holds a teller can spend from the ledger.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

A CallerTeller only works in the token's own realm (guardHome returns ErrForeignCallerTeller anywhere else), so "whoever holds a teller can spend" isn't true for this one. Master's wording was right:

Suggested change
// Unexported: whoever holds a teller can spend from the ledger.
// Keep the teller unexported: it is a spend capability. It is built from
// the ledger, which never leaves this realm, and it only works here.

@davd-gzl davd-gzl Oct 21, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Applied in c47b9df.

Comment thread docs/resources/coins-and-tokens.md Outdated
## Choosing between Coins and GRC20 tokens

Pick Coins when a token only needs to be held and sent. The chain moves them
with no contract code, and a user attaches them to any call with `-send`.

@alexiscolin alexiscolin Oct 21, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Nit: since #6062, a -send to a function that never looks at the payment fails with UnobservedSendError, so -send doesn't work on just any call.

Suggested change
with no contract code, and a user attaches them to any call with `-send`.
with no contract code, and a user pays a realm by attaching them with `-send`
to a function that reads `unsafe.OriginSend()`.

@davd-gzl davd-gzl Oct 21, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Applied in c47b9df.

Comment thread AGENTS.md Outdated
- In a crossing function, derive caller identity from `cur.Previous()` and write no `cur.IsCurrent()` guard: the runtime puts `cur` into the current realm-context on entry, so the check is always true. `IsCurrent()` belongs on a realm value a caller hands over as an ordinary argument, `rlm` by convention, which may be left over from an earlier call.
- Never read `chain/runtime/unsafe.PreviousRealm()` in a crossing function: it walks the frame stack, so it answers from wherever it is called, while `cur.Previous()` names the realm that was current when `cur` was minted. Delete any `chain/runtime/unsafe` import sitting beside a `cur realm` parameter.
- When editing a realm that accepts payment via `banker.OriginSend()`, the caller guard must be `cur.Previous().IsUserCall()`, not `IsUser()`. `IsUser()` accepts `maketx run` ephemeral realms, which can consume the origin-send envelope before calling your function and bypass the payment check. See [docs/resources/effective-gno.md § Verifying inbound Coin payments](docs/resources/effective-gno.md#verifying-inbound-coin-payments).
- When editing a realm that accepts payment via `banker.OriginSend()`, the caller guard must be `cur.Previous().IsUserCall()`, not `IsUser()`. `IsUser()` accepts `maketx run` ephemeral realms, which can consume the origin-send envelope before calling your function and bypass the payment check. See [docs/resources/coins-and-tokens.md § Verifying inbound Coin payments](docs/resources/coins-and-tokens.md#verifying-inbound-coin-payments).

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Since this line changes anyway: banker.OriginSend() doesn't exist, OriginSend lives in chain/runtime/unsafe (line 111 has the same name).

Suggested change
- When editing a realm that accepts payment via `banker.OriginSend()`, the caller guard must be `cur.Previous().IsUserCall()`, not `IsUser()`. `IsUser()` accepts `maketx run` ephemeral realms, which can consume the origin-send envelope before calling your function and bypass the payment check. See [docs/resources/coins-and-tokens.md § Verifying inbound Coin payments](docs/resources/coins-and-tokens.md#verifying-inbound-coin-payments).
- When editing a realm that accepts payment via `unsafe.OriginSend()`, the caller guard must be `cur.Previous().IsUserCall()`, not `IsUser()`. `IsUser()` accepts `maketx run` ephemeral realms, which can consume the origin-send envelope before calling your function and bypass the payment check. See [docs/resources/coins-and-tokens.md § Verifying inbound Coin payments](docs/resources/coins-and-tokens.md#verifying-inbound-coin-payments).

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Applied in c47b9df, line 111 too. Line 109 now deletes only a chain/runtime/unsafe import that PreviousRealm() alone uses, since the payment check reads unsafe.OriginSend() from it. 14784a5..c47b9df

…d-tokens

Co-authored-by: Alexis Colin <7622257+alexiscolin@users.noreply.github.com>
@davd-gzl
davd-gzl requested a review from alexiscolin October 21, 2026 16:50
@davd-gzl

Copy link
Copy Markdown
Member Author

This time it should be good, I will do a second PR for the rest of the initial issue, tysm for your review!

This branch has not been deployed

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

Labels

📖 documentation Improvements or additions to documentation 🧾 package/realm Tag used for new Realms or Packages. 📄 top-level-md

Projects

No open projects

Development

Successfully merging this pull request may close these issues.

4 participants