feat: improve documentation about typing in intelligent contracts

[epsjunior]

PR: Improve Documentation About Typing in Intelligent Contracts

Overview

Comprehensive restructure and improvement of typing documentation for Intelligent Contracts, addressing GenLayer-specific types, storage patterns, and memory management.

Changes Made

🔄 Documentation Restructure

• Split monolithic types.mdx into focused sub-pages:
  • types/address.mdx - Address type usage and conversions
  • types/primitive.mdx - Integer, string, bytes, boolean types with conversions
  • types/collections.mdx - DynArray and TreeMap with practical examples
  • types/dataclasses.mdx - Dataclass patterns for method parameters/returns

📚 Enhanced Storage Documentation

• Merged storage content from separate files into single storage.mdx
• Added memory management section with gl.storage.inmem_allocate and gl.storage.copy_to_memory
• Included working examples from GenVM repository

🎯 Key Technical Corrections

• Generic types: Require gl.storage.inmem_allocate for instantiation
• Collections: Use storage fields instead of local instantiation
• Storage objects: Cannot be converted to string - use gl.storage.copy_to_memory
• Method signatures: Use int for numeric parameters, TreeMap[str, typing.Any] for returns

Documentation Structure

types/
├── address.mdx # Address conversions and usage
├── primitive.mdx # Basic types with conversion utilities ├── collections.mdx # DynArray and TreeMap patterns
└── dataclasses.mdx # Structured data for contracts

Impact

• Better organization - developers can find specific type information quickly
• Accurate examples - all code snippets are tested and work correctly
• Comprehensive coverage - addresses Address types, primitives, collections, dataclasses, and storage
• Single source of truth - eliminates redundant and conflicting information

Summary by CodeRabbit

• New Features

  • Storage API path updated to a nested module and a "copy to memory" utility added for using storage data in non-deterministic contexts.

• Documentation

  • New, user-focused guides for Address types, primitive types, dataclasses, and storage-compatible collections (DynArray, TreeMap), plus memory-management examples and usage patterns.
  • Clarified distinction between storage views and in-memory objects.

• Chores

  • Added metadata for type documentation and removed an older aggregated types overview.

[netlify]

✅ Deploy Preview for genlayer-docs ready!

Name	Link
🔨 Latest commit	470db9d
🔍 Latest deploy log	https://app.netlify.com/projects/genlayer-docs/deploys/689eac88c0d0e90008dde4c3
😎 Deploy Preview	https://deploy-preview-273--genlayer-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Warning

Rate limit exceeded

@epsjunior has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 8 minutes and 6 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between befd267 and 470db9d.

📒 Files selected for processing (1)

• pages/developers/intelligent-contracts/types/primitive.mdx (1 hunks)

Walkthrough

Adds new and reorganized documentation for GenVM intelligent-contract types (primitive, address, collections, dataclasses), introduces a Memory Management section with updated storage API usage (gl.storage.inmem_allocate and gl.storage.copy_to_memory), adds types metadata, and removes the previous aggregated types page.

Changes

Cohort / File(s)	Change Summary
Memory Management Documentation Update pages/developers/intelligent-contracts/storage.mdx	Replaced top-level API calls with gl.storage.inmem_allocate(...), added a Memory Management section showing allocation, gl.storage.copy_to_memory, examples for plain and generic dataclasses, and clarified storage views vs in-memory data.
Types Metadata pages/developers/intelligent-contracts/types/_meta.json	Added JSON metadata mapping type category keys (address, primitive, collections, dataclasses) to descriptive strings.
Address Type Documentation pages/developers/intelligent-contracts/types/address.mdx	New doc introducing the Address type: creation from hex/base64/bytes, conversions, storage and calldata usage, examples, and several example contract classes and public methods.
Collection Types Documentation pages/developers/intelligent-contracts/types/collections.mdx	New doc for storage-compatible collections (DynArray, TreeMap) with examples, contracts demonstrating operations, and storage-compatible dataclass usage patterns.
Dataclasses Documentation pages/developers/intelligent-contracts/types/dataclasses.mdx	New doc describing @allow_storage dataclasses, generic dataclasses, example contracts using dataclasses in storage and collections.
Primitive Types Documentation pages/developers/intelligent-contracts/types/primitive.mdx	New doc covering sized integers, bigint, strings/bytes, booleans, type conversion utilities, example contracts, and reference tables for integer ranges.
Removed Aggregate Types Page pages/developers/intelligent-contracts/types.mdx	Deleted the previous aggregate types overview page; content redistributed into the new specific type pages.

Sequence Diagram(s)

sequenceDiagram
participant User
participant Contract
participant Storage
participant Memory
User->>Contract: Invoke public method (read/write)
Contract->>Storage: Allocate or access storage object (gl.storage.inmem_allocate for allocation)
alt Need nondeterministic/memory ops
Contract->>Storage: gl.storage.copy_to_memory(storage_obj)
Storage-->>Memory: returns in-memory object
Contract->>Memory: operate (print, str(), mutate in nondet block)
Memory-->>Contract: return results
else Work with storage views directly
Contract->>Storage: read/return storage view
end
Contract->>User: Return result

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• cristiam86
• kp2pml30

Poem

"I hopped through docs with nibbling care,
New types and storage now lay bare.
Addresses, arrays, dataclasses bright—
I copy to memory, then take flight.
🐇✨ — A rabbit cheering devs tonight"

✨ Finishing Touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch dxp-554-improve-documentation-about-typing-in-intelligent-contracts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

• Visit our Status Page to check the current availability of CodeRabbit.
• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

Actionable comments posted: 7

♻️ Duplicate comments (1)

pages/developers/intelligent-contracts/types/collections.mdx (1)

179-182: get_profile suffers from the same return-type inconsistency

The method claims to return TreeMap[str, typing.Any] but actually yields a UserProfile.
Align the annotation with the real return value or convert the dataclass as shown above.

🧹 Nitpick comments (9)

pages/developers/intelligent-contracts/types/_meta.json (1)

1-6: Align key order & trim trailing whitespace for consistent nav diffs

Navigation order is controlled by the key order in _meta.json. Keeping keys sorted (or at least consistently ordered) avoids noisy diffs when another contributor adds a page later. Also, Line 6 has a trailing space after the closing brace.

- "primitive": "Primitive Types",- "collections": "Collection Types",- "dataclasses": "Dataclasses"+ "collections": "Collection Types",+ "dataclasses": "Dataclasses",+ "primitive": "Primitive Types"
}

(If the current order is intentional, feel free to ignore the re-ordering but please still remove the trailing space.)

pages/developers/intelligent-contracts/types/primitive.mdx (2)

15-30: Code snippet is missing required imports, may confuse newcomers

The example references gl, u8, u24 … which are not imported. A minimal import header keeps the snippet self-contained:

-class IntegerTypes(gl.Contract):+# Prepend this+from genlayer import *++class IntegerTypes(gl.Contract):

Same applies to later snippets that use DynArray, TreeMap, etc.

---

56-63: StringBytesTypes also needs imports for clarity

Same import gap noted above; add:

fromgenlayerimport*

pages/developers/intelligent-contracts/storage.mdx (2)

90-100: Tiny typo: comment says “error: data is absent” yet example uses correct call

Consider rewriting the comment to emphasise why the plain constructor fails and why inmem_allocate is mandatory for generics, e.g.:

User() → error (generic field data lacks concrete storage backing)

Minor, but improves comprehension.

---

125-143: Snippet needs the obvious imports

from typing import Generic, TypeVar (for T) is missing. Adds clarity and prevents readers from thinking GenVM magically provides them.

pages/developers/intelligent-contracts/types/dataclasses.mdx (1)

35-42: Generic dataclass example misses TypeVar declaration

Add the usual boilerplate so readers can paste-&-run:

fromtypingimportTypeVar, GenericT=TypeVar("T")

pages/developers/intelligent-contracts/types/address.mdx (2)

55-63: Custom format specifiers need prior mention

Not all readers will realise Address.__format__ supports "b64"/"cd". A one-liner just above the method explaining supported specifiers prevents confusion.

---

68-90: Import omissions recur

Add from genlayer import * (and optionally from typing import *) at the top of each snippet so examples are self-contained.

pages/developers/intelligent-contracts/types/collections.mdx (1)

70-72: Remove unused imports

json is never referenced and typing is required only for the erroneous return types flagged below.
Eliminate the unused json (and typing once the return-type fix is applied) to keep examples lean.

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6e0fc05 and ac49db3.

📒 Files selected for processing (6)

• pages/developers/intelligent-contracts/storage.mdx (2 hunks)
• pages/developers/intelligent-contracts/types/_meta.json (1 hunks)
• pages/developers/intelligent-contracts/types/address.mdx (1 hunks)
• pages/developers/intelligent-contracts/types/collections.mdx (1 hunks)
• pages/developers/intelligent-contracts/types/dataclasses.mdx (1 hunks)
• pages/developers/intelligent-contracts/types/primitive.mdx (1 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

pages/**/_meta.json

📄 CodeRabbit Inference Engine (CLAUDE.md)

pages/**/_meta.json: Navigation is controlled by _meta.json files in each directory
Edit _meta.json files to change page ordering or titles
Update corresponding _meta.json to include the new page when adding new pages

Files:

• pages/developers/intelligent-contracts/types/_meta.json

pages/**/*.mdx

📄 CodeRabbit Inference Engine (CLAUDE.md)

pages/**/*.mdx: All content is in MDX format supporting React components
Import and use custom components within MDX files
Create .mdx file in appropriate pages/ subdirectory when adding new pages
All content should support React components in MDX files

Files:

• pages/developers/intelligent-contracts/storage.mdx
• pages/developers/intelligent-contracts/types/address.mdx
• pages/developers/intelligent-contracts/types/dataclasses.mdx
• pages/developers/intelligent-contracts/types/primitive.mdx
• pages/developers/intelligent-contracts/types/collections.mdx

🧠 Learnings (9)

📓 Common learnings

Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Setup Guide Updates (pages/validators/setup-guide.mdx): Update version references in download examples and version lists, update configuration examples with new contract addresses when applicable, enhance command documentation when new features are added to existing commands, update genesis block configuration in consensus section when network upgrades occur

Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Update configuration examples with new contract addresses in setup-guide.mdx when applicable

Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : GenVM diagnostics integration affects the doctor command behavior and should be documented in the validator setup guide

Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Update consensus contract addresses and genesis block number in setup-guide.mdx when network upgrades occur

📚 Learning: applies to pages/**/_meta.json : update corresponding _meta.json to include the new page when adding...

Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/**/_meta.json : Update corresponding _meta.json to include the new page when adding new pages

Applied to files:

• pages/developers/intelligent-contracts/types/_meta.json

📚 Learning: next.js automatically updates next-env.d.ts file during dependency updates, including adding new typ...

Learnt from: epsjunior
PR: genlayerlabs/genlayer-docs#244
File: next-env.d.ts:3-6
Timestamp: 2025-07-09T18:27:44.033Z
Learning: Next.js automatically updates next-env.d.ts file during dependency updates, including adding new type references like "next/navigation-types/compat/navigation" when upgrading versions. These changes are not manual edits and should not be flagged as problematic.

Applied to files:

• pages/developers/intelligent-contracts/types/_meta.json

📚 Learning: applies to pages/**/_meta.json : navigation is controlled by _meta.json files in each directory...

Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/**/_meta.json : Navigation is controlled by _meta.json files in each directory

Applied to files:

• pages/developers/intelligent-contracts/types/_meta.json

📚 Learning: applies to pages/**/_meta.json : edit _meta.json files to change page ordering or titles...

Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/**/_meta.json : Edit _meta.json files to change page ordering or titles

Applied to files:

• pages/developers/intelligent-contracts/types/_meta.json

📚 Learning: applies to pages/validators/setup-guide.mdx : update configuration examples with new contract addres...

Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Update configuration examples with new contract addresses in setup-guide.mdx when applicable

Applied to files:

• pages/developers/intelligent-contracts/storage.mdx
• pages/developers/intelligent-contracts/types/address.mdx

📚 Learning: applies to pages/validators/setup-guide.mdx : setup guide updates (pages/validators/setup-guide.mdx)...

Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Setup Guide Updates (pages/validators/setup-guide.mdx): Update version references in download examples and version lists, update configuration examples with new contract addresses when applicable, enhance command documentation when new features are added to existing commands, update genesis block configuration in consensus section when network upgrades occur

Applied to files:

• pages/developers/intelligent-contracts/storage.mdx
• pages/developers/intelligent-contracts/types/address.mdx

📚 Learning: applies to pages/validators/setup-guide.mdx : update consensus contract addresses and genesis block ...

Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Update consensus contract addresses and genesis block number in setup-guide.mdx when network upgrades occur

Applied to files:

• pages/developers/intelligent-contracts/types/address.mdx

📚 Learning: applies to pages/validators/setup-guide.mdx : consensus contract addresses change with network upgra...

Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Consensus contract addresses change with network upgrades and must be updated in configuration examples

Applied to files:

• pages/developers/intelligent-contracts/types/address.mdx

🪛 LanguageTool

pages/developers/intelligent-contracts/types/primitive.mdx

[style] ~146-~146: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...64| 0 to 18,446,744,073,709,551,615 | Very large numbers | |u128` | 0 to 2^128 - 1 | C...

(EN_WEAK_ADJECTIVE)

---

[style] ~156-~156: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...,775,808 to 9,223,372,036,854,775,807 | Very large signed values | | i128 | -2^127 to 2^...

(EN_WEAK_ADJECTIVE)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Redirect rules - genlayer-docs
• GitHub Check: Header rules - genlayer-docs
• GitHub Check: Pages changed - genlayer-docs

🔇 Additional comments (2)

pages/developers/intelligent-contracts/types/primitive.mdx (1)

78-81: concatenate_strings hard-codes UTF-8 assumptions

If any of the inputs are bytes, this will throw.
Either enforce str in the signature (as done) or show a guarded conversion example to avoid beginners copy-pasting brittle code.

pages/developers/intelligent-contracts/types/dataclasses.mdx (1)

55-56: Return type for get_items should communicate encoded form

If the intention is to return the encoded (calldata) representation, spell that out in prose; otherwise return DynArray[Item[str]] and let the encoder do its job.

[kp2pml30]

Thanks for your hard work! I left a couple of comments

I also think that I haven't seen phrase like "u256 can't be used in method signatures". Unfortunately, due to my mistake that was the case, but fix will be published to everyone soon

[kp2pml30]

Thanks!