README: sub-word struct members are sign-extended (intN) or left-aligned (bytesN), not always zero-padded

[thedavidmeister]

Closes #24

README L268-269 said every sub-word type is "padded with 0's such that they retain the same uint256 equivalent value". That holds for unsigned integers, address, bool and enums only. In memory, signed integers are sign-extended (int8(-1) occupies 0xff…ff, i.e. uint256(int256(x)), not uint256(uint8(x)) = 0x00…ff) and bytesN is left-aligned with zero padding on the right (bytes4(0x01020304) occupies 0x01020304 followed by 28 zero bytes, i.e. uint256(bytes32(x)), not uint256(uint32(x))). A reader reproducing a struct hash off-chain from "uint256 equivalent values" gets the wrong hash for any struct with a signed or fixed-bytes field. The sentence now states the layout per type family, gives the conversion that yields the word for each, and closes with the rule the hashing pattern actually depends on: the hash is of the word as laid out. The README change is only that sentence; sibling PRs edit other README sections.

test/MemoryLayout.t.sol pins every claim the paragraph makes. A SubWord struct has one member per sub-word family (bool, address, uint32, enum, int8, bytes4); each test mloads that member's word and asserts it equals the word Solidity's own conversion produces for the same value. The README's two literal examples, the "occupies a full word" rule, the 4-word Foo and the bytes1[] word list each have their own test.

QA

• Discriminating tests: testNestedStructIsOnePointerWord(uint256), testDeeplyNestedStructIsOnePointerWordPerLevel(uint256,uint256), testDynamicMembersArePointerWords(uint256[],bytes), testBytesAllocationRoundsUpToWords, testBytesAllocationRoundsUpToWordsForAnyLength(uint16), testNewStringAllocatesLikeNewBytes(uint16), testStringLayoutIsBytesLayout(bytes), testSubWordMembersOccupyFullWords, testBoolIsZeroPadded(bool), testAddressIsZeroPadded(address), testUnsignedIntIsZeroPadded(uint32), testEnumIsZeroPadded, testSignedIntIsSignExtended(int8), testInt8MinusOneIsAllOnes, testFixedBytesIsLeftAligned(bytes4), testBytes4ExampleIsLeftAligned, testFooIsFourWords, testBytes1ArrayIsWordList (test/MemoryLayout.t.sol) — fails on base: n/a — README-only claims; the tests pin what the README now says and fail under the README's previous wording (mutants below).

• Mutations applied: 57/57 KILLED, 0 survived, 0 no-run (mutation-probe, suite = CI's sol-shell forge test, fuzz.runs 1024). Lines are in test/MemoryLayout.t.sol at this head.

  line	mutation	killed by
  68	6 * 0x20 → 5 * 0x20 (six sub-word members allocate five words)	testSubWordMembersOccupyFullWords
  67	assertEq(ptr, fmpBefore) → fmpBefore + 0x20	testSubWordMembersOccupyFullWords
  75	x ? 1 : 0 → x ? 0 : 1	testBoolIsZeroPadded
  75	offset 0x00 → 0x20 (reads addr)	testBoolIsZeroPadded
  82	uint256(uint160(x)) → uint256(bytes32(bytes20(x))) (left-aligned)	testAddressIsZeroPadded
  82	offset 0x20 → 0x40 (reads u)	testAddressIsZeroPadded
  89	uint256(x) → uint256(bytes32(bytes4(x))) (left-aligned)	testUnsignedIntIsZeroPadded
  89	offset 0x40 → 0x60 (reads colour)	testUnsignedIntIsZeroPadded
  98	uint256(uint8(c)) → uint256(bytes32(bytes1(uint8(c)))) (left-aligned)	testEnumIsZeroPadded
  98	offset 0x60 → 0x40 (reads u)	testEnumIsZeroPadded
  106	uint256(int256(x)) → uint256(uint8(x)) (old README claim: zero-padded)	testSignedIntIsSignExtended
  106	offset 0x80 → 0xa0 (reads b)	testSignedIntIsSignExtended
  113	type(uint256).max → uint256(uint8(int8(-1))) (old README claim: 0x00…ff)	testInt8MinusOneIsAllOnes
  112	offset 0x80 → 0x60 (reads colour)	testInt8MinusOneIsAllOnes
  114	w != uint256(uint8(int8(-1))) → ==	testInt8MinusOneIsAllOnes
  121	uint256(bytes32(x)) → uint256(uint32(x)) (old README claim: right-aligned)	testFixedBytesIsLeftAligned
  121	offset 0xa0 → 0x80 (reads i)	testFixedBytesIsLeftAligned
  129	uint256(0x01020304) << 224 → uint256(0x01020304) (old README claim: 0x00…01020304)	testBytes4ExampleIsLeftAligned
  128	offset 0xa0 → 0x80 (reads i)	testBytes4ExampleIsLeftAligned
  130	w != uint256(uint32(0x01020304)) → ==	testBytes4ExampleIsLeftAligned
  152	0x80 → 0x60 (address not a full word)	testFooIsFourWords
  151	assertEq(ptr, fmpBefore) → fmpBefore + 0x20	testFooIsFourWords
  182	0x20 + 3 * 0x20 → 0x20 + 3 (elements packed one byte each)	testBytes1ArrayIsWordList
  183	uint256(bytes32(bytes1(0x01))) → uint256(uint8(0x01)) (right-aligned)	testBytes1ArrayIsWordList
  176	mload(add(arr, 0x20)) → mload(arr) (first element read at the length prefix)	testBytes1ArrayIsWordList
  181	assertEq(len, 3) → 3 * 0x20	testBytes1ArrayIsWordList
  180	assertEq(ptr, fmpBefore) → fmpBefore + 0x20	testBytes1ArrayIsWordList
  M28	Outer size wrong reading: Foo inlined into Outer (0x20 + 0x80)	testNestedStructIsOnePointerWord(uint256)
  M29	Outer pointer word wrong reading: word expected to be Foo's first word	testNestedStructIsOnePointerWord(uint256)
  M30	Outer first word offset: x read at the pointer word	testNestedStructIsOnePointerWord(uint256)
  M31	Outer ptr: struct expected one word after the free pointer	testNestedStructIsOnePointerWord(uint256)
  M32	Outermost size wrong reading: Outer inlined into Outermost (0x20 + 0x40)	testDeeplyNestedStructIsOnePointerWordPerLevel(uint256,uint256)
  M33	Outer-in-chain size wrong reading: Foo inlined into the middle Outer	testDeeplyNestedStructIsOnePointerWordPerLevel(uint256,uint256)
  M34	Outermost pointer word wrong reading: nested pointers flatten to the innermost Foo	testDeeplyNestedStructIsOnePointerWordPerLevel(uint256,uint256)
  M35	chain follow offset: Outer's pointer word read at its first word	testDeeplyNestedStructIsOnePointerWordPerLevel(uint256,uint256)
  M36	Outermost ptr: struct expected one word after the free pointer	testDeeplyNestedStructIsOnePointerWordPerLevel(uint256,uint256)
  M37	Foo.c word wrong reading: word expected to be the array's length (inlined)	testDynamicMembersArePointerWords(uint256[],bytes)
  M38	Foo.d word wrong reading: word expected to be the bytes' length (inlined)	testDynamicMembersArePointerWords(uint256[],bytes)
  M39	Foo.c offset: reads the d pointer word	testDynamicMembersArePointerWords(uint256[],bytes)
  M40	Foo.d offset: reads past the struct	testDynamicMembersArePointerWords(uint256[],bytes)
  M41	bytes(1) size wrong reading: no rounding (0x20 + 1)	testBytesAllocationRoundsUpToWords()
  M42	bytes(33) size wrong reading: rounded down (0x20 + 0x20)	testBytesAllocationRoundsUpToWords()
  M43	bytes(33) size wrong reading: no rounding (0x20 + 33)	testBytesAllocationRoundsUpToWords()
  M44	bytes(33) length wrong reading: length word holds the rounded size	testBytesAllocationRoundsUpToWords()
  M45	bytes(1) length offset: length read at the content	testBytesAllocationRoundsUpToWords()
  M46	bytes(33) ptr: expected one word after the free pointer	testBytesAllocationRoundsUpToWords()
  M47	bytes(n) size wrong reading: no rounding	testBytesAllocationRoundsUpToWordsForAnyLength(uint16)
  M48	bytes(n) size wrong reading: rounded down	testBytesAllocationRoundsUpToWordsForAnyLength(uint16)
  M49	bytes(n) length wrong reading: length word holds the rounded size	testBytesAllocationRoundsUpToWordsForAnyLength(uint16)
  M50	new bytes/string size wrong reading: no rounding	testNewStringAllocatesLikeNewBytes(uint16)
  M51	new string wrong reading: string allocates one word more than bytes	testNewStringAllocatesLikeNewBytes(uint16)
  M52	new string length wrong reading: length word holds the rounded size	testNewStringAllocatesLikeNewBytes(uint16)
  M53	new string ptr: expected one word after the free pointer	testNewStringAllocatesLikeNewBytes(uint16)
  M54	concat string content offset wrong reading: string has no length prefix	testStringLayoutIsBytesLayout(bytes)
  M55	concat string length wrong reading: length word counts words	testStringLayoutIsBytesLayout(bytes)
  M56	concat string wrong reading: string allocates one word more than bytes	testStringLayoutIsBytesLayout(bytes)
  M57	concat string ptr: expected one word after the free pointer	testStringLayoutIsBytesLayout(bytes)

• Oracle: Solidity's own type conversions of the same value — uint256(x), uint256(uint160(x)), uint256(uint8(c)), uint256(int256(x)), uint256(bytes32(x)) — compared against the word mload reads back from the struct member (solc 0.8.25, the compiler the README's linked layout doc describes); the literal examples compare against type(uint256).max and uint256(0x01020304) << 224 written out. Sizes compare the free memory pointer before and after the one allocation. Nothing under test is this library.

• Category check: the sweep also found the README alignment claim ("the allocator will still move the free memory pointer to a multiple of 32") false for bytes.concat/abi.encodePacked under the legacy pipeline — not fixed here, filed as README claims the allocator always keeps the free memory pointer at a multiple of 32; bytes.concat and abi.encodePacked leave it unaligned under the legacy pipeline #38; the rounding tests above pin only the new path. issue asks (A) state intN is sign-extended, (B) state bytesN is left-aligned, (C) both occupy one full word and the hash is of the word as laid out, not a uint256 conversion; covered A, B, C, and kept the zero-padded family (unsigned, address, bool, enums) the old sentence was true for, so the rule is stated per family rather than by two counterexamples.

Notes

• The local git-hooks.nix pre-commit installed by the sol-shell runs deno fmt over Markdown and reflows the whole README (main does not satisfy it; CI's static job runs slither / forge fmt --check / single-contract, not denofmt). The README commit bypasses that hook so the diff stays local to the sentence.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FvfmeRQKubdbFW1GL3kmib

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Team

Run ID: 7f77beef-a1df-444e-b0e3-b50bc92c20f5

📥 Commits

Reviewing files that changed from the base of the PR and between 22e0445 and 66cab2d.

📒 Files selected for processing (1)

• README.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Walkthrough

The README now documents Solidity memory representations for sub-word types. It specifies right alignment, zero padding, sign extension, and left alignment rules. It also clarifies that hashing uses the word as laid out in memory.

Changes

Memory Layout Documentation

Layer / File(s)	Summary
Document type-specific memory layout rules README.md	The memory-layout description now covers unsigned values, addresses, booleans, enums, signed integers, and bytesN values. It states that hashing uses the laid-out word.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Merge Risk: ⚪ Minimal · up to 66cab

This updates documentation to describe type-specific Solidity memory layouts and full-word hashing behavior. No merge-readiness risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The README documents zero-padding for unsigned integers, address, bool, and enums; sign extension for intN; left alignment with right-side padding for bytesN; and hashing of the laid-out word. These c…
Out of Scope Changes check	✅ Passed	The pull request changes only the README content that addresses issue #24. No unrelated code or documentation changes are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the README correction for signed integers and bytesN memory alignment. It is specific, concise, and directly related to the main change.

Full details: Linked Issues check

Explanation

The README documents zero-padding for unsigned integers, address, bool, and enums; sign extension for intN; left alignment with right-side padding for bytesN; and hashing of the laid-out word. These changes satisfy issue #24.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 2026-09-03-issue-24-subword-layout

---

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

_{Comment @coderabbitai help to get the list of available commands.}

[thedavidmeister]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.