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

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

Motivation

Solution

Implements struct decoding for state diff output
handle_struct_recursive 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

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

…-in-state-diffs

@onbjerg

* add @onbjerg * add @0xrusowsky

…ty::Gas` (#11358) fix(lint): 'unwrapped-modifier-logic' incorrectly marked with Severity::Gas

zerosnacks · 2025-08-22T11:01:10Z

testdata/default/cheats/StateDiffStructTest.t.sol

+    // Helper function to check if a string contains a substring
+    function assertContains(string memory haystack, string memory needle, string memory message) internal pure {
+        bytes memory haystackBytes = bytes(haystack);
+        bytes memory needleBytes = bytes(needle);
+
+        if (needleBytes.length > haystackBytes.length) {
+            revert(message);
+        }
+
+        bool found = false;
+        for (uint256 i = 0; i <= haystackBytes.length - needleBytes.length; i++) {
+            bool isMatch = true;
+            for (uint256 j = 0; j < needleBytes.length; j++) {
+                if (haystackBytes[i + j] != needleBytes[j]) {
+                    isMatch = false;
+                    break;
+                }
+            }
+            if (isMatch) {
+                found = true;
+                break;
+            }
+        }
+
+        if (!found) {
+            revert(message);
+        }
+    }
+}


can we move this to a helper, this is duplicated in https://github.com/foundry-rs/foundry/pull/11381/files#diff-7c006befc48f0502d1653777375b064ac35b0866dc7fe26fb332e78a5edc9371

zerosnacks

Implementation lgtm, note on duplicate utility function after merging https://github.com/foundry-rs/foundry/pull/11381/files#diff-7c006befc48f0502d1653777375b064ac35b0866dc7fe26fb332e78a5edc9371

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 added 4 commits August 19, 2025 14:06

feat: format slots to only significant bits in vm.getStateDiff output

aa36022

encode_prefixed

3cfefdc

nit

850dc6c

Merge branch 'yash/decode-label-state-diffs' into yash/decode-structs…

8f9f82f

…-in-state-diffs

Base automatically changed from yash/decode-label-state-diffs to master August 19, 2025 13:02

zerosnacks and others added 13 commits August 20, 2025 11:51

chore: add @onbjerg to CODEOWNERS (#11343)

6e3120b

* add @onbjerg * add @0xrusowsky

resolve conflicts

0ea49a2

fix: disable tx gas limit cap (#11347)

a11c347

chore(deps): bump all dependencies (#11349)

f9964de

chore: use get_or_calculate_hash better (#11350)

6ebfaf3

resolve more conflicts

cc09011

fix(lint): 'unwrapped-modifier-logic' incorrectly marked with `Severi…

9c78c61

…ty::Gas` (#11358) fix(lint): 'unwrapped-modifier-logic' incorrectly marked with Severity::Gas

feat: identify and decode nested structs

cbbbdb6

resolve conflicts

156bc80

cleanup

55249e8

decode structs and members recursively

1b1f626

cleanup

499abf6

doc fix

a1de1dc

yash-atreya marked this pull request as ready for review August 20, 2025 14:08

yash-atreya requested review from DaniPopes, klkvr, mattsse, grandizzy, zerosnacks, onbjerg and 0xrusowsky as code owners August 20, 2025 14:08

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

bb255b3

zerosnacks reviewed Aug 22, 2025

View reviewed changes

zerosnacks self-requested a review August 22, 2025 11:02

zerosnacks requested changes Aug 22, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

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

Uh oh!

yash-atreya commented Aug 18, 2025 •

edited

Loading

Uh oh!

zerosnacks Aug 22, 2025

Uh oh!

zerosnacks left a comment

Uh oh!

Uh oh!

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

Are you sure you want to change the base?

feat(cheatcodes): decode structs 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!

zerosnacks Aug 22, 2025

Choose a reason for hiding this comment

Uh oh!

zerosnacks left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

yash-atreya commented Aug 18, 2025 •

edited

Loading