Skip to content

Add Pages and Words libraries for MIP-8 storage pages - #9

Open
mmv08 wants to merge 1 commit into
mainfrom
pageref-contract
Open

mmv08 wants to merge 1 commit into
mainfrom
pageref-contract

Conversation

@mmv08

@mmv08 mmv08 commented Sep 4, 2026

Copy link
Copy Markdown
Collaborator

This PR adds two small storage libraries for MIP-8 pages and changes CI to use the upstream Foundry with added monad support.

Contracts added:

  • Pages implements the page and slot arithmetic from MIP-8 together with a PageIndex type and PageHandle struct to reserve a storage slot for deriving the page from that slot number.
  • Words is a helper to read and write storage without assembly, same approach as OZ's StorageSlot lib

A basic usage sketch:

import {PageHandle} from "monad-std/utils/storage/Pages.sol";

contract Vault {
    PageHandle internal balances;

    function balanceOf(uint256 i) external view returns (uint256) {
        return balances.page().words()[i];
    }

    function set(uint256 i, uint256 v) external {
        balances.page().words()[i] = v;
    }
}

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟢 Approval recommended

The implementations are internally consistent, bounded appropriately, documented, and covered by focused fuzz tests.

Pull request overview

Adds MIP-8 page arithmetic and typed storage access utilities, with tests, documentation, dependency locking, and upstream Foundry CI support.

Changes:

  • Adds Pages, PageIndex, PageHandle, and Words.
  • Adds fuzz tests for page arithmetic and storage pointers.
  • Updates Foundry configuration, dependencies, CI, and documentation.
File summaries
File Description
src/utils/storage/Pages.sol Implements MIP-8 page and slot arithmetic.
src/utils/storage/Words.sol Adds typed arbitrary-slot storage access.
test/Pages.t.sol Tests page derivation and arithmetic.
test/Words.t.sol Tests exact-slot reads and writes.
README.md Documents the new storage utilities.
foundry.toml Enables Monad and CI fuzz configuration.
foundry.lock Locks the forge-std dependency.
.gitmodules Configures the forge-std submodule.
.github/workflows/test.yml Uses upstream Foundry and checks out submodules.
Review details
  • Files reviewed: 9/10 changed files
  • Comments generated: 0
  • Review effort level: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

MIP-8 groups storage into 4 KiB pages of 128 slots, so contracts that
lay their storage out by page need page and slot arithmetic. Pages
gives them the PageIndex type, the PageHandle type that derives a page
from its own storage slot, checked slot arithmetic that reverts past
the end of storage, and one custom error for an offset outside a page.

A PageHandle is a one-slot struct declared where the structure that
uses the page lives, as a state variable or inside a struct, array, or
mapping. Its page contains keccak256(abi.encode(slot)), where a dynamic
array declared in its place would start its data, so distinct
declarations get distinct pages. The slot itself is never written.

Pages hands out slot numbers, and reading or writing one takes the
same three lines of assembly in every consumer. Words.ref turns a
slot number into a Word storage pointer once, in the library, so
storage laid out by slot is plain Solidity at the call site. It takes
uint256 to match Pages and adds no runtime dependency. It is named ref
because solc 0.8.36 warns that at will become a keyword.

Tests use forge-std, added as a test-only submodule, and check reverts
with vm.expectRevert through a harness contract. CI now installs
upstream Foundry, which ships Monad support since v1.8.0, checks out
submodules, and runs the fuzz tests at 10,000 runs through the ci
profile the workflow already selected but that was never defined.
foundry.toml selects the Monad network family for local runs too.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟢 Approval recommended

The storage utilities, tests, dependency setup, documentation, and CI changes are consistent and complete.

Review details
  • Files reviewed: 9/10 changed files
  • Comments generated: 0 new
  • Review effort level: Balanced

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants