feat(cheatcodes): decode structs and mappings in state diff output #11331

yash-atreya · 2025-08-18T12:19:15Z

Motivation

Solution

Decode Structs:

Implements struct decoding for state diff output
handle_struct processes both single-slot and multi-slot structs, recursing through nested
structures.
Displays all members with their decoded values; for multi-slot structs, shows the specific member at
the accessed slot

Decode Mappings: feat(cheatcodes): decode mappings in state diffs #11381
Refactor PR to extract slot identification and decoding logic to crates/common: refactor: moves state diff decoding to common #11413 which will aid in resolving feat(invariants): improve storage decoding for subsequent fuzz runs #11334 and Cannot find the storage slot for a public string variable #3869

Example:

contract DiffTest {
    // slot 0
    struct TestStruct {
        uint128 a;
        uint128 b;
    }

    // Multi-slot struct (spans 3 slots)
    struct MultiSlotStruct {
        uint256 value1; // slot 1
        address addr; // slot 2 (takes 20 bytes, but uses full slot)
        uint256 value2; // slot 3
    }

    // Nested struct with MultiSlotStruct as inner
    struct NestedStruct {
        MultiSlotStruct inner; // slots 4-6 (spans 3 slots)
        uint256 value; // slot 7
        address owner; // slot 8
    }

    TestStruct internal testStruct;
    MultiSlotStruct internal multiSlotStruct;
    NestedStruct internal nestedStruct;

    function setStruct(uint128 a, uint128 b) public {
        testStruct.a = a;
        testStruct.b = b;
    }

    function setMultiSlotStruct(uint256 v1, address a, uint256 v2) public {
        multiSlotStruct.value1 = v1;
        multiSlotStruct.addr = a;
        multiSlotStruct.value2 = v2;
    }

    function setNestedStruct(uint256 v1, address a, uint256 v2, uint256 v, address o) public {
        nestedStruct.inner.value1 = v1;
        nestedStruct.inner.addr = a;
        nestedStruct.inner.value2 = v2;
        nestedStruct.value = v;
        nestedStruct.owner = o;
    }
}

contract StateDiffStructTest is DSTest {
    Vm constant vm = Vm(HEVM_ADDRESS);
    DiffTest internal test;

    function setUp() public {
        test = new DiffTest();
    }

    function testDiffs() public {
        // Start recording state diffs
        vm.startStateDiffRecording();

        // Set some values to trigger state changes
        test.setStruct(1, 2);
        // Get the state diff as JSON
        string memory td = vm.getStateDiffJson();

        // Debug: log the JSON for inspection
        emit log_string("TestStruct Diff:");
        emit log_string(td);

        test.setMultiSlotStruct(123456789, address(0xdEaDbEeF), 987654321);

        // Get the state diff as JSON
        string memory md = vm.getStateDiffJson();

        // Debug: log the JSON for inspection
        emit log_string("MultiSlotStruct Diff:");
        emit log_string(md);

        test.setNestedStruct(
            111111111,
            address(0xCAFE),
            222222222,
            333333333,
            address(0xBEEF)
        );

        // Get the state diff as JSON
        string memory nd = vm.getStateDiffJson();

        // Debug: log the JSON for inspection
        emit log_string("NestedStruct Diff:");
        emit log_string(nd);
    }
}

TestStruct Diff

{
  "0xce71065d4017f316ec606fe4422e11eb2c47c246": {
    "label": null,
    "contract": "default/cheats/StateDiffStructTest.t.sol:DiffTest",
    "balanceDiff": null,
    "nonceDiff": null,
    "stateDiff": {
      "0x0000000000000000000000000000000000000000000000000000000000000000": {
        "previousValue": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "newValue": "0x0000000000000000000000000000000200000000000000000000000000000001",
        "label": "testStruct",
        "type": "struct DiffTest.TestStruct",
        "offset": 0,
        "slot": "0",
        "members": [
          {
            "label": "a",
            "type": "uint128",
            "offset": 0,
            "slot": "0",
            "decoded": {
              "previousValue": "0",
              "newValue": "1"
            }
          },
          {
            "label": "b",
            "type": "uint128",
            "offset": 16,
            "slot": "0",
            "decoded": {
              "previousValue": "0",
              "newValue": "2"
            }
          }
        ]
      }
    }
  }
}

MultiSlotStruct Diff

{
  "0xce71065d4017f316ec606fe4422e11eb2c47c246": {
    "label": null,
    "contract": "default/cheats/StateDiffStructTest.t.sol:DiffTest",
    "balanceDiff": null,
    "nonceDiff": null,
    "stateDiff": {
      "0x0000000000000000000000000000000000000000000000000000000000000000": { .. },
      "0x0000000000000000000000000000000000000000000000000000000000000001": {
        "previousValue": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "newValue": "0x00000000000000000000000000000000000000000000000000000000075bcd15",
        "decoded": {
          "previousValue": "0",
          "newValue": "123456789"
        },
        "label": "multiSlotStruct.value1",
        "type": "uint256",
        "offset": 0,
        "slot": "1"
      },
      "0x0000000000000000000000000000000000000000000000000000000000000002": {
        "previousValue": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "newValue": "0x00000000000000000000000000000000000000000000000000000000deadbeef",
        "decoded": {
          "previousValue": "0x0000000000000000000000000000000000000000",
          "newValue": "0x00000000000000000000000000000000DeaDBeef"
        },
        "label": "multiSlotStruct.addr",
        "type": "address",
        "offset": 0,
        "slot": "2"
      },
      "0x0000000000000000000000000000000000000000000000000000000000000003": {
        "previousValue": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "newValue": "0x000000000000000000000000000000000000000000000000000000003ade68b1",
        "decoded": {
          "previousValue": "0",
          "newValue": "987654321"
        },
        "label": "multiSlotStruct.value2",
        "type": "uint256",
        "offset": 0,
        "slot": "3"
      }
    }
  }
}

NestedStruct Diff

{
  "0xce71065d4017f316ec606fe4422e11eb2c47c246": {
    "label": null,
    "contract": "default/cheats/StateDiffStructTest.t.sol:DiffTest",
    "balanceDiff": null,
    "nonceDiff": null,
    "stateDiff": {
      "0x0000000000000000000000000000000000000000000000000000000000000000": { .. },
      "0x0000000000000000000000000000000000000000000000000000000000000001": { .. },
      "0x0000000000000000000000000000000000000000000000000000000000000002": { .. },
      "0x0000000000000000000000000000000000000000000000000000000000000003": { .. },
      "0x0000000000000000000000000000000000000000000000000000000000000004": {
        "previousValue": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "newValue": "0x00000000000000000000000000000000000000000000000000000000069f6bc7",
        "decoded": {
          "previousValue": "0",
          "newValue": "111111111"
        },
        "label": "nestedStruct.inner.value1",
        "type": "uint256",
        "offset": 0,
        "slot": "4"
      },
      "0x0000000000000000000000000000000000000000000000000000000000000005": {
        "previousValue": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "newValue": "0x000000000000000000000000000000000000000000000000000000000000cafe",
        "decoded": {
          "previousValue": "0x0000000000000000000000000000000000000000",
          "newValue": "0x000000000000000000000000000000000000cafE"
        },
        "label": "nestedStruct.inner.addr",
        "type": "address",
        "offset": 0,
        "slot": "5"
      },
      "0x0000000000000000000000000000000000000000000000000000000000000006": {
        "previousValue": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "newValue": "0x000000000000000000000000000000000000000000000000000000000d3ed78e",
        "decoded": {
          "previousValue": "0",
          "newValue": "222222222"
        },
        "label": "nestedStruct.inner.value2",
        "type": "uint256",
        "offset": 0,
        "slot": "6"
      },
      "0x0000000000000000000000000000000000000000000000000000000000000007": {
        "previousValue": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "newValue": "0x0000000000000000000000000000000000000000000000000000000013de4355",
        "decoded": {
          "previousValue": "0",
          "newValue": "333333333"
        },
        "label": "nestedStruct.value",
        "type": "uint256",
        "offset": 0,
        "slot": "7"
      },
      "0x0000000000000000000000000000000000000000000000000000000000000008": {
        "previousValue": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "newValue": "0x000000000000000000000000000000000000000000000000000000000000beef",
        "decoded": {
          "previousValue": "0x0000000000000000000000000000000000000000",
          "newValue": "0x000000000000000000000000000000000000bEEF"
        },
        "label": "nestedStruct.owner",
        "type": "address",
        "offset": 0,
        "slot": "8"
      }
    }
  }
}

PR Checklist

Added Tests
Added Documentation
Breaking changes

* feat(cheatcodes): decode mappings in state diffs * feat: decode nested mappings * assert vm.getStateDiff output * feat: add `keys` fields to `SlotInfo` in case of mappings * remove wrapper * refactor: moves state diff decoding to common (#11413) * refactor: storage decoder * cleanup * dedup MappingSlots by moving it to common * move decoding logic into SlotInfo * rename to SlotIndentifier * docs * fix: delegate identification according to encoding types * clippy + fmt * docs fix * fix * merge match arms * merge ifs * recurse handle_struct

crates/cheatcodes/src/evm.rs

crates/common/src/slot_identifier.rs

zerosnacks

👍 Overall lgtm! Few small nits

I think users will really enjoy this feature

DaniPopes · 2025-08-25T20:41:50Z

crates/common/src/slot_identifier.rs

+}
+
+/// Formats a [`DynSolValue`] as a raw string without type information and only the value itself.
+pub fn format_value(value: &DynSolValue) -> String {


this is common::fmt

reused in 8be596d

Co-authored-by: zerosnacks <95942363+zerosnacks@users.noreply.github.com>

grandizzy

lgtm! pending @zerosnacks @DaniPopes , thank you

testdata/default/cheats/StateDiffTestUtils.sol

crates/common/src/mapping_slots.rs

DaniPopes · 2025-08-28T09:31:27Z

lgtm, nitz, merge when done

zerosnacks

lgtm 👍 , pending Dani's nits

@onbjerg

…oundry-rs#11331) * feat(`forge`): sample typed storage values * arc it * nit * clippy * nit * strip file prefixes * fmt * don't add adjacent values to sample * feat(cheatcodes): add contract identifier to AccountStateDiffs * forge fmt * doc nits * fix tests * feat(`cheatcodes`): include `SlotInfo` in SlotStateDiff * cleanup + identify slots of static arrays * nits * nit * nits * test + nits * docs * handle 2d arrays * use DynSolType * feat: decode storage values * doc nit * skip decoded serialization if none * nit * fmt * fix * fix * fix * feat(cheatcodes): decode structs in state diff output * fix * while decode * fix: show only decoded in plaintext / display output + test * feat: format slots to only significant bits in vm.getStateDiff output * encode_prefixed * nit * chore: add @onbjerg to `CODEOWNERS` (foundry-rs#11343) * add @onbjerg * add @0xrusowsky * resolve conflicts * fix: disable tx gas limit cap (foundry-rs#11347) * chore(deps): bump all dependencies (foundry-rs#11349) * chore: use get_or_calculate_hash better (foundry-rs#11350) * resolve more conflicts * fix(lint): 'unwrapped-modifier-logic' incorrectly marked with `Severity::Gas` (foundry-rs#11358) fix(lint): 'unwrapped-modifier-logic' incorrectly marked with Severity::Gas * feat: identify and decode nested structs * cleanup * decode structs and members recursively * cleanup * doc fix * feat(cheatcodes): decode mappings in state diffs (foundry-rs#11381) * feat(cheatcodes): decode mappings in state diffs * feat: decode nested mappings * assert vm.getStateDiff output * feat: add `keys` fields to `SlotInfo` in case of mappings * remove wrapper * refactor: moves state diff decoding to common (foundry-rs#11413) * refactor: storage decoder * cleanup * dedup MappingSlots by moving it to common * move decoding logic into SlotInfo * rename to SlotIndentifier * docs * fix: delegate identification according to encoding types * clippy + fmt * docs fix * fix * merge match arms * merge ifs * recurse handle_struct * dedup assertContains test util * fix * Update crates/common/src/slot_identifier.rs Co-authored-by: zerosnacks <95942363+zerosnacks@users.noreply.github.com> * Review changes: simplify get or insert, use common fmt * alloy-dyn-abi.workspace * nits --------- Co-authored-by: Yash Atreya <yash@Yashs-Laptop.local> Co-authored-by: zerosnacks <95942363+zerosnacks@users.noreply.github.com> Co-authored-by: Matthias Seitz <matthias.seitz@outlook.de> Co-authored-by: DaniPopes <57450786+DaniPopes@users.noreply.github.com> Co-authored-by: srdtrk <59252793+srdtrk@users.noreply.github.com> Co-authored-by: 0xrusowsky <90208954+0xrusowsky@users.noreply.github.com> Co-authored-by: grandizzy <38490174+grandizzy@users.noreply.github.com> Co-authored-by: grandizzy <grandizzy.the.egg@gmail.com>

yash-atreya added 30 commits August 4, 2025 15:58

feat(forge): sample typed storage values

926e8d5

arc it

8ec91b3

nit

cfd4a15

clippy

c56c920

nit

90a1dea

strip file prefixes

e7caa86

fmt

bccf3ad

don't add adjacent values to sample

fd6ecd6

Merge branch 'master' into yash/fuzz-storage-values-by-type

a4c4a79

feat(cheatcodes): add contract identifier to AccountStateDiffs

f62bcb8

forge fmt

1b4520f

Merge branch 'master' into yash/state-diff-storage-labels

cc29481

doc nits

729ea8e

fix tests

2a8da88

feat(cheatcodes): include SlotInfo in SlotStateDiff

3c74ed9

cleanup + identify slots of static arrays

85a225b

nits

a4228ef

nit

1853d8e

nits

5b8b95b

test + nits

e619e0d

docs

caf21b9

handle 2d arrays

e9630a0

use DynSolType

b44b410

feat: decode storage values

e78b087

doc nit

ebcef04

skip decoded serialization if none

65db931

nit

7d3c87b

Merge branch 'master' into yash/state-diff-storage-labels

fe8b59d

fmt

e63e817

fix

f9ffcea

yash-atreya changed the title ~~feat(cheatcodes): decode structs in state diff output~~ feat(cheatcodes): decode structs and mappings in state diff output Aug 25, 2025

dedup assertContains test util

7460161

zerosnacks self-requested a review August 25, 2025 13:48

yash-atreya added 2 commits August 25, 2025 20:08

Merge branch 'master' into yash/decode-structs-in-state-diffs

befdf4b

fix

5cd7b12

zerosnacks reviewed Aug 25, 2025

View reviewed changes

crates/cheatcodes/src/evm.rs Outdated Show resolved Hide resolved

zerosnacks reviewed Aug 25, 2025

View reviewed changes

crates/common/src/slot_identifier.rs Show resolved Hide resolved

zerosnacks requested changes Aug 25, 2025

View reviewed changes

DaniPopes reviewed Aug 25, 2025

View reviewed changes

grandizzy and others added 2 commits August 26, 2025 10:56

Update crates/common/src/slot_identifier.rs

398c5ab

Co-authored-by: zerosnacks <95942363+zerosnacks@users.noreply.github.com>

Review changes: simplify get or insert, use common fmt

8be596d

grandizzy requested review from DaniPopes and zerosnacks August 26, 2025 08:53

alloy-dyn-abi.workspace

b850bc7

grandizzy previously approved these changes Aug 26, 2025

View reviewed changes

DaniPopes reviewed Aug 28, 2025

View reviewed changes

testdata/default/cheats/StateDiffTestUtils.sol Outdated Show resolved Hide resolved

crates/common/src/mapping_slots.rs Outdated Show resolved Hide resolved

zerosnacks previously approved these changes Aug 28, 2025

View reviewed changes

nits

fbcd265

yash-atreya dismissed stale reviews from zerosnacks and grandizzy via fbcd265 August 28, 2025 10:54

yash-atreya enabled auto-merge (squash) August 28, 2025 10:54

yash-atreya requested review from grandizzy and zerosnacks August 28, 2025 11:04

grandizzy approved these changes Aug 28, 2025

View reviewed changes

yash-atreya merged commit 2dad626 into master Aug 28, 2025
22 checks passed

yash-atreya deleted the yash/decode-structs-in-state-diffs branch August 28, 2025 11:12

github-project-automation bot moved this to Done in Foundry Aug 28, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(cheatcodes): decode structs and mappings in state diff output #11331

feat(cheatcodes): decode structs and mappings in state diff output #11331

Uh oh!

yash-atreya commented Aug 18, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

zerosnacks left a comment

Uh oh!

DaniPopes Aug 25, 2025

Uh oh!

grandizzy Aug 26, 2025

Uh oh!

grandizzy left a comment

Uh oh!

Uh oh!

Uh oh!

DaniPopes commented Aug 28, 2025

Uh oh!

zerosnacks left a comment

Uh oh!

Uh oh!

Uh oh!

feat(cheatcodes): decode structs and mappings in state diff output #11331

feat(cheatcodes): decode structs and mappings in state diff output #11331

Uh oh!

Conversation

yash-atreya commented Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Solution

PR Checklist

Uh oh!

Uh oh!

Uh oh!

zerosnacks left a comment

Choose a reason for hiding this comment

Uh oh!

DaniPopes Aug 25, 2025

Choose a reason for hiding this comment

Uh oh!

grandizzy Aug 26, 2025

Choose a reason for hiding this comment

Uh oh!

grandizzy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

DaniPopes commented Aug 28, 2025

Uh oh!

zerosnacks left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

yash-atreya commented Aug 18, 2025 •

edited

Loading