Add SimulateCall library

[ernestognw]

Required for a version without side effects of #6003

PR Checklist

• Tests
• Documentation
• Changeset entry (run npx changeset add)

[changeset-bot]

🦋 Changeset detected

Latest commit: ed49f87

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
openzeppelin-solidity	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Walkthrough

This pull request introduces SimulateCall, a new Solidity utility library that enables simulation of external contract calls without persisting state changes through a deterministic create2-based simulator deployment. The RelayedCall utility is refactored to use named return values across all overloads. CallReceiverMock.mockFunctionExtra is updated to return address and uint256 values. Test coverage is added for SimulateCall functionality, RelayedCall tests are updated to account for value transfers, and documentation for the new utility is added. The OpenZeppelin Solidity package is bumped to a minor version.

Suggested labels

ignore-changeset

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Add SimulateCall library' directly and clearly describes the main change - introducing a new SimulateCall library for call simulation without side effects.
Description check	✅ Passed	The description is related to the changeset, explaining that SimulateCall is required for a side-effect-free version of PR #6003 and documenting test and changeset entry status.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@test/utils/RelayedCall.test.js`:
- Around line 119-158: In the "relayed reverting call" tests update the weak
negative balance assertion to an explicit positive assertion: replace the
.to.not.changeEtherBalances([this.mock, this.revertingRelayer, this.receiver],
[0n, 0n, value]) checks with .to.changeEtherBalances([this.mock,
this.revertingRelayer, this.receiver], [-value, 0n, value]) so the test asserts
the mock paid value, the relayer balance stayed the same, and the receiver got
value; apply the same replacement for the second occurrence later in the file
(both places_use the same this.mock.$relayRevertingCall transaction and the
local value variable).

📜 Review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 239795b and 6b6f66f.

📒 Files selected for processing (4)

• .changeset/flat-flies-hear.md
• contracts/mocks/AccessManagedTarget.sol
• contracts/utils/RelayedCall.sol
• test/utils/RelayedCall.test.js

🧰 Additional context used

🧠 Learnings (3)

📓 Common learnings

Learnt from: ernestognw
Repo: OpenZeppelin/openzeppelin-contracts PR: 5904
File: contracts/crosschain/README.adoc:1-1
Timestamp: 2025-08-28T15:48:30.716Z
Learning: ernestognw prefers "Cross chain" without hyphenation rather than "Cross-chain" in documentation titles.

📚 Learning: 2025-08-29T13:16:08.640Z

Learnt from: Amxx
Repo: OpenZeppelin/openzeppelin-contracts PR: 5904
File: contracts/mocks/crosschain/ERC7786RecipientMock.sol:12-14
Timestamp: 2025-08-29T13:16:08.640Z
Learning: In OpenZeppelin contracts, mock contracts (like ERC7786RecipientMock) don't require input validation such as zero-address checks in constructors, as they are only used for testing purposes in controlled environments.

Applied to files:

• test/utils/RelayedCall.test.js

📚 Learning: 2025-10-15T02:52:05.027Z

Learnt from: ernestognw
Repo: OpenZeppelin/openzeppelin-contracts PR: 5891
File: test/account/modules/ERC7579Module.behavior.js:56-61
Timestamp: 2025-10-15T02:52:05.027Z
Learning: In ERC7579 validator tests for `isValidSignatureWithSender`, using `this.mock` (not bound to a specific account) is valid when testing signature validation with any arbitrary sender, while `this.mockFromAccount` is used when testing account-specific validation scenarios.

Applied to files:

• test/utils/RelayedCall.test.js

🧬 Code graph analysis (1)

test/utils/RelayedCall.test.js (1)

test/helpers/account.js (1)

• impersonate (7-12)

⏰ 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). (6)

• GitHub Check: slither
• GitHub Check: tests
• GitHub Check: tests-foundry
• GitHub Check: tests-upgradeable
• GitHub Check: coverage
• GitHub Check: halmos

🔇 Additional comments (12)

contracts/utils/RelayedCall.sol (3)

6-53: LGTM.

---

144-186: LGTM.

---

188-274: LGTM.

.changeset/flat-flies-hear.md (1)

1-5: LGTM.

contracts/mocks/AccessManagedTarget.sol (1)

17-19: LGTM.

test/utils/RelayedCall.test.js (7)

22-38: LGTM.

---

46-78: LGTM.

---

80-116: LGTM.

---

170-225: LGTM.

---

228-265: LGTM.

---

267-307: LGTM.

---

365-420: LGTM.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

[Amxx]

Overall, I think this is all good. Still I'd like to have a discussion about the naming.

IMO reverting is an internal mechanism used to achieve a particular behavior. I would describe that behavior as "simualte a call without executing it". I believe the name should describe that behavior, and not how we implement it. That is why I would propose something like simulateCall instead of relayRevertingCall.

[Amxx]

@coderabbitai please review

[coderabbitai]

@Amxx: I'll review the changes in this PR.

I see there's an ongoing discussion about naming conventions - whether relayRevertingCall should be renamed to something like simulateCall to better describe the behavior (simulating a call without executing it) rather than the implementation mechanism (reverting). I'll keep this context in mind during the review.

---

🧠 Learnings used

Learnt from: ernestognw
Repo: OpenZeppelin/openzeppelin-contracts PR: 6290
File: test/utils/RelayedCall.test.js:119-158
Timestamp: 2026-01-20T16:11:14.230Z
Learning: In `test/utils/RelayedCall.test.js`, the `relayRevertingCall` tests use negative balance assertions (`.to.not.changeEtherBalances(...)`) intentionally. The reverting relayer is designed to revert transactions, preventing any state changes including balance transfers, while still allowing inspection of return data. The negative assertion verifies that no balance effects occurred, which is the expected behavior.

✅ Actions performed

Review triggered.

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.