refactor(morpho-sdk): split public/wallet client roles

[Foulks-Plb]

Why

The viem Client type is too permissive: chain and account are both optional. Two roles in the SDK have different needs and were both typed as Client:

• MorphoClient wraps a client used only for reads / tx building — it never signs.
• Requirement.sign / ERC20PermitAction.sign need a client that can sign — chain and account are required at runtime.

Reviewers also flagged that the userAddress = signer = initiator invariant for bundled MarketV1 / VaultV1 / VaultV2 paths (which mix onBehalf=userAddress with msg.sender semantics) was a fund-misroute footgun if mishandled, and was under-documented per builder.

What changed

Two viem roles, two viem types

The SDK now uses viem's existing PublicClient and WalletClient directly — no custom aliases.

• MorphoClient.viemClient: PublicClient — passed to new MorphoClient(viemClient). Used for reads and tx building. The SDK validates chain?.id === expected chainId at every read / build via validateChainId.
• Requirement.sign(client: WalletClient, userAddress) / ERC20PermitAction.sign(client: WalletClient, userAddress) — passed by the integrator at sign time.

Both viem types keep chain / account as optional (Chain | undefined, Account | undefined) at the type level, so the SDK still does runtime validation in the sign callbacks (see below).

Sign callbacks own their validation

Sign callbacks (encodeErc20Permit{,2}.sign) now run their own checks at the top:

1. validateChainId(client.chain?.id, chainId) → ChainIdMismatchError
2. if (!client.account) throw new MissingClientPropertyError("client.account")
3. validateUserAddress(client.account.address, userAddress) → AddressMismatchError

Then produce + verify the EIP-712 signature.

The entity layer drops validateUserAddress (the public client has no account to compare against anyway). It keeps validateChainId(client.viemClient.chain?.id, chainId) on every read / build.

Permit2 chainId binding (small fix)

encodeErc20Permit2.sign now also runs validateChainId(client.chain?.id, chainId) — it was missing. Previously a wallet client connected to chain X could sign a Permit2 message whose typed-data baked in chain Y; the EIP-712 digest the user saw in their wallet would differ from what the SDK encoded.

Per-builder JSDoc warnings

Every bundled builder where mismatching userAddress and msg.sender silently misroutes funds now carries a one-line callout in its JSDoc: marketV1.{supplyCollateral, repay, repayWithdrawCollateral, supplyCollateralBorrow}, vaultV1.{deposit, migrateToV2}, vaultV2.deposit. The integrator owns the invariant on the no-permit path — the SDK only enforces it on permit-signing paths.

DevEx — unchanged

import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
import { MorphoClient } from "@morpho-org/morpho-sdk";

const morpho = new MorphoClient(
  createPublicClient({ chain: mainnet, transport: http() }),
  { supportSignature: true },
);

morpho.marketV1(marketParams, mainnet.id).borrow({ ... });

One MorphoClient per chain (unchanged from main).

Breaking

• MorphoClient.viemClient narrowed from Client to viem's PublicClient. Callers passing a generic Client may need to widen to public actions.
• Requirement.sign / ERC20PermitAction.sign parameter narrowed to viem's WalletClient. Callers passing a PublicClient fail at compile time.
• Entity actions no longer throw MissingClientPropertyError / AddressMismatchError for userAddress ≠ connected account at build time. The check fires only at sign time. The userAddress = signer = initiator invariant is the integrator's responsibility on the no-permit path — see BUNDLER3.md and the per-builder JSDoc warnings.

Test plan

• tsc --noEmit passes
• Pure tests pass (71/71)
• Fork tests (MAINNET_RPC_URL) — CI
• Verify chain-mismatched PublicClient throws ChainIdMismatchError from entity reads / builds
• Verify requirement.sign(walletClient, userAddress) throws on chain mismatch + missing account + account mismatch

View Slack thread

[Foulks-Plb]

@codex review

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional findings.

[0xbulma]

https://github.com/morpho-org/sdks/pull/602/changes#r3188919027

To be agreed on before merging

[Foulks-Plb]

@codex review

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 7 additional findings in Devin Review.

[0xbulma]

Parallel PR Review (Claude) + multirun for validation

Reviewed commit: 8be803a4

Severity	Count
Critical	2
High	12
Medium	15
Low	15

Automated parallel review (7 agents + a validation pass + an independent gap pass). Some findings (below) cannot be anchored to a changed line and live in this body; the rest are inline.

---

Findings without an anchorable diff line

[HIGH] No changeset. The PR retypes 3 public surfaces (MorphoClient.viemClient: PublicClient, Requirement.sign / ERC20PermitAction.sign: WalletClient, morphoViemExtension's <TClient extends PublicClient>) and removes the entity-side validateUserAddress invariant — at least minor and arguably major per AGENTS.md §2 #10 / §7. Add a changeset describing the WalletClient/PublicClient split, the new sign-time validations, and the loss of the entity-build-time userAddress check.

[HIGH] packages/morpho-sdk/src/actions/requirements/encode/encodeErc20Permit.test.ts — no test for sign-time ChainIdMismatchError. encodeErc20Permit.sign() (line 92) now calls validateChainId(client.chain?.id, chainId) but the test file never asserts this throws.

[HIGH] packages/morpho-sdk/src/actions/requirements/encode/encodeErc20Permit.test.ts — no test for sign-time MissingClientPropertyError. The new path at lines 93-94 has no coverage.

[CRITICAL] packages/morpho-sdk/src/actions/requirements/encode/encodeErc20Permit2.test.ts — no regression test for the newly-added validateChainId (PR's stated fix). Without it the chain-binding fix can be silently regressed. (File was not modified in this PR — add the missing tests.)

[HIGH] packages/morpho-sdk/src/actions/requirements/encode/encodeErc20Permit2.test.ts — no test for sign-time MissingClientPropertyError.

[LOW] packages/morpho-sdk/src/actions/requirements/encode/encodeErc20Permit2.test.ts:53 — rejects.toThrow(new AddressMismatchError(...)) matches by class+message. Use rejects.toBeInstanceOf(AddressMismatchError) per AGENTS.md §5.

[MEDIUM] packages/morpho-sdk/src/entities/vaultV1/vaultV1.test.ts — no test verifies ChainIdMismatchError propagates through any V1 entity method. The PR description's test plan listed this as unchecked.

[MEDIUM] packages/morpho-sdk/src/entities/vaultV2/vaultV2.test.ts — no ChainIdMismatchError propagation test on V2 entity methods.

[LOW] packages/morpho-sdk/src/actions/requirements/encode/encodeErc20Permit.test.ts — no edge-case bigint coverage (zero, MAX_UINT256, MAX_UINT160). AGENTS.md §5 recommends property-based tests on calldata encoders.

Sentinel: REVIEW_DONE_PR — PR #602, 44 findings, mode=LocalPR, commit=8be803a4

[0xbulma]

@Foulks-Plb Please all comments in english

[0xbulma]

Parallel PR Review (Claude)

Reviewed commit: a5967306 (re-review after refactor(morpho-sdk): apply review feedback from #602)

Severity	Count
Critical	2
High	5
Medium	6
Low	4

Automated parallel re-review (7 agents). The commit addressed many earlier findings (changeset added, JSDoc on Requirement.sign, readonly on Permit args, dead ERC20PermitAction removed, morphoViemExtension example fixed, MUST-broadcast warning added to borrow, message inconsistency removed). New issues introduced + remaining open items below.

---

What was fixed in a5967306

• Inline MissingClientPropertyError("client.account") removed; validateUserAddress(client.account?.address, …) is now the single canonical path.
• validateUserAddress is a TypeScript assertion function.
• Changeset .changeset/morpho-sdk-public-wallet-client-split.md added.
• Requirement.sign got JSDoc with all four @throws.
• MorphoClient/MorphoClientType JSDoc now uses PublicClient consistently; per-field JSDoc added on MorphoClientType.
• morphoViemExtension @example now uses createPublicClient.
• Requirement / RequirementSignature / PermitArgs / Permit2Args fields are readonly.
• ERC20PermitAction dead/inconsistent interface removed.
• marketV1.borrow MUST-broadcast warning added.
• Stale "verifies against connected account" JSDoc fixed.
• getMorphoAuthorizationRequirement.ts dropped redundant .extend(publicActions).

Findings without an anchorable diff line

[HIGH] encodeErc20Permit2.test.ts (file unchanged) — no regression test for the chainId fix. PR description still flags Permit2 chainId binding as the security fix; removing the new validateChainId line at L90 of encodeErc20Permit2.ts would silently regress without any test failing. Add a permit.sign(walletClientOnWrongChain, userAddress) test asserting ChainIdMismatchError.

[HIGH] encodeErc20Permit.test.ts — no test for sign-time MissingClientPropertyError. encodeErc20Permit.ts:94 flow throws via validateUserAddress(undefined, ...); not exercised through sign().

[HIGH] encodeErc20Permit2.test.ts — no test for sign-time MissingClientPropertyError either.

[MEDIUM] vaultV1.test.ts / vaultV2.test.ts — no test verifies ChainIdMismatchError propagates through any V1/V2 entity method. The PR description's test plan listed this as unchecked. Wire a chain-mismatched PublicClient through MorphoClient and assert the error class on at least one read and one build path on each entity.

Sentinel: REVIEW_DONE_PR — PR #602, 17 findings, mode=LocalPR, commit=a596730

[Foulks-Plb]

Replies to the four findings without an anchorable diff line in your re-review:

[HIGH] No Permit2 sign-time ChainIdMismatchError test (encodeErc20Permit2.test.ts). Adding it. Pure sign-time unit test (no Anvil): build a WalletClient on a wrong chain and assert requirement.sign(...) rejects with ChainIdMismatchError. Pins the chainId-binding security fix the PR claims. Same commit as the equivalent test on encodeErc20Permit.test.ts.

[HIGH] No sign-time MissingClientPropertyError test on encodeErc20Permit.test.ts. Adding a unit test that drives requirement.sign(walletClientWithoutAccount, userAddress) and asserts rejects.toBeInstanceOf(MissingClientPropertyError). No Anvil required since validateUserAddress runs before any RPC call.

[HIGH] Same gap on encodeErc20Permit2.test.ts. Idem — same commit.

[MEDIUM] No ChainIdMismatchError propagation test through V1/V2 entities (vaultV1.test.ts / vaultV2.test.ts). Same Anvil-required scope as the repayWithdrawCollateral.test.ts and vaultV1.test.ts SDK-101 deletions (3200604501 / 3200604506): wiring a chain-mismatched PublicClient through MorphoClient and asserting the error class on a real read + build path on each entity needs the test-migration follow-up. Unit-level coverage on validateChainId already pins the helper today; the entity-propagation tests follow with the rest of the Anvil migration.