feat(examples): pluggable grc20 ledger storage + p/nt/hashmap (flat gas for large ledgers)

[omarsy]

Summary

Adds a KV storage-backend seam to p/demo/tokens/grc20 and a new
p/nt/hashmap/v0 package so token ledgers can opt into storage-access gas
that stays flat as the ledger grows, instead of growing with holder count.

This addresses the state-scaling half of #5906. The default backend is
unchanged (avl.Tree), so this is fully backwards-compatible and opt-in.

Why

A cold GRC20 transfer costs ~6M gas at 1 holder but ~18M at ~1,000,000
holders. The cause is the data structure, not the contract: avl.Tree
materializes its search path as one persisted object per node, and the base
store charges a flat ~59k gas per cold object read, so a transfer loads
O(log N) objects. Measured cold (fresh keeper, empty object cache — the state
a validator is in after cache GC), same transfer op:

ledger size	avl	hashmap (1024)	bptree (fanout 128)
20,000	13.8M	4.3M	7.8M
100,000	15.5M	4.5M	10.7M
1,000,000	18.6M	5.7M (−69%)	11.7M (−37%)

• avl at 1M reproduces the real on-chain test_atone transfer (18.3M) —
  independent confirmation of the mechanism.
• hashmap (a native-map bucket array; each bucket is a single persisted
  object regardless of entry count) stays flat: O(1) object loads per op.
• bptree (already in-tree) rides the same seam and keeps ordered
  iteration, which hashmap trades away.

Full analysis and 1..1M measurements are in the ADR.

Changes

New package

• examples/gno.land/p/nt/hashmap/v0/ — hashmap.gno (Map: Get/Set/Remove/Has/Size/Iterate, FNV-1a bucketing, fixed power-of-two bucket count, sizing guidance), hashmap_test.gno, gnomod.toml.

grc20 seam (backwards-compatible, default avl)

• examples/gno.land/p/demo/tokens/grc20/types.gno — add KV interface (satisfied by *avl.Tree, *hashmap.Map, *bptree.BPTree), Option, WithStorage; ledger fields become KV.
• examples/gno.land/p/demo/tokens/grc20/token.gno — NewToken gains variadic opts ...Option; ledger built from the chosen backend (default avl.NewTree).
• examples/gno.land/p/demo/tokens/grc20/storage_option_test.gno — full token flow over all three backends through the one seam.

ADR

• gno.land/adr/prxxxx_hashmap_ledger.md — context, decision, measured results (incl. the 1M scaling and the bptree comparison), alternatives (native VM storage, block-level warm/cold gas pricing), consequences.

Notes / open discussion

• This is one lever (data layer). The swap congestion that saturated test13
  is a different workload; block-level warm/cold gas pricing would help it
  and every contract automatically — flagged in the ADR as a separate,
  protocol-level proposal for maintainers to weigh.
• Sizing was measured: the default 1024 buckets stays flat from ~1k to ~1M
  entries, and over-sizing (4096) is counter-productive (every op decodes the
  whole bucket-pointer array). Documented in the package.
• FNV-1a uses a fixed seed (grindable); the bounded-impact limitation is
  documented in the package and ADR.

AI-assisted (investigation, implementation, and the cold-cache measurements);
reviewed and owned by the author.

🤖 Generated with Claude Code

[Gno2D2]

🛠 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:

• Report a bug with the bot.
• View the bot’s configuration file.

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: omarsy/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

[notJoon]

based on ADR, I measured the costs by running a local chain with gnodev. while the measured costs did not exactly match, I confirmed that they shoed the same trends described in docs

[omarsy]

@notJoon, the gnodev run caught a real issue: my harness was undercounting by ~2×. It simulated only 2 of the store's 7 gas dimensions and skipped the depth-gas multiplier on cold IAVL reads. Re-measured through the real cache-wrapped, gas-metered store (DefaultGasConfig + DefaultParams), it now matches your gnodev (hashmap ≈16.2M vs your ~17.4M).

Corrected cold transfer:

holders	avl	two-level hashmap
20k	27.9M	16.2M (−42%)
100k	29.8M	16.5M (−45%)
1M	~35M	18.8M (−46%)

Itemizing that also surfaced why even hashmap floors at ~16M cold: a fixed ~10.7M IAVL cost, of which ~7.67M (half a cold tx) is the VM re-reading its 13 governance params as 13 separate depth-multiplied keys — backend-independent, on top of the ledger reads. Bundling those into one KV read is a measured flat −7.08M/tx; orthogonal to this PR, so I'll open it separately.

Direction and fix are unchanged — only the magnitudes (~2× low) and the old "18M @ 1M" anchor were wrong.

[omarsy]

One more correction. I re-measured on current master, which has since merged the B+tree fast-index store (#5937/#5938). My numbers above were on a pre-fast-index base, so they're now too high: the fast-index cut cold reads 5-10x (a cold GET went 590k to 59k, param reads 590k to 118k).

Corrected cold transfer (real cache-store metering, master, bptree fast-index + Fixed depth pins applied):

holders	avl	hashmap
20k	19.66M	7.97M (-59%)
100k	21.59M	8.25M (-62%)

Two things flip vs my earlier post:

1. This PR looks better, not worse. With the fixed floor now small, the hashmap advantage is -59% at 20k and -62% at 100k (was -42%), and it grows with ledger size. The dominant avl cost is now the base-store tree walk (~8.2M of 19.66M), which is exactly what the hashmap removes.
2. The "param floor" I flagged is mostly gone. The fast-index already cut it from ~7.67M to ~1.65M, so the separate param-bundle idea is now a ~1.5M top-up rather than a ~7M lever.

Net: the thesis holds and the fix is stronger than even the corrected numbers suggested. I'd just been measuring on a base that predated the fast-index.