feat(morpho-sdk): add transaction plan by prd-carapulse[bot] · Pull Request #856 · morpho-org/sdks

prd-carapulse · 2026-07-08T08:10:28Z

Adds a first-class TransactionPlan API for app-side transaction review and execution flows, stacked on hermes/marketv2-action-flows-implementation.

Summary:

Adds lazy TransactionPlan, PreparedTransactionPlan, and ExecutableTransactionPlan under src/transactionPlan/.
Entity action-flow outputs across Vault V1, Vault V2, Blue, and Midnight return TransactionPlan instances while preserving buildTx(...) / getRequirements(...) destructuring.
Primary app-facing surface is now request-shaped: signatureRequests and callRequests.
callRequests contains viem-compatible calls in execution order and includes the final intent call when it can be previewed. After signatures, prepared.build(signatures).callRequests always includes the final intent call last.
Previous requirement-oriented fields remain only as deprecated aliases for compatibility.
Adds semantic intents (tokenApproval, operatorAuthorization, contractCall, midnightOfferRootSignature, finalTransaction), request-kind flow values (single_call, call_requests, signature_requests, mixed_requests), sequential signAll(), ordered viem-compatible calls, and missing-signature validation.
Supports signature-dependent final transactions whose unsigned final call cannot be previewed before signatures are collected; reading prepared.finalTx before it is available throws a typed SDK error.

Interface rationale:

VVRM/vaults app currently starts from raw SDK requirements, then turns them into user steps: approval txs, offchain signatures, and the final tx. At the app/UX boundary, “requirements” are not meaningful; “signature requests” and “call requests” are.
Markets app already models flows as SignatureRequest[] plus ordered CallRequest[]. PRs morpho-org/morpho-apps#3567 and #3568 had to adapt the SDK output into that shape manually, including appending the final call after prerequisite calls.
The SDK should internalize the neutral structure and metadata, not labels/callbacks/hooks/product branching. Apps still own labels, analytics, callbacks, action-flow construction, and UX policy.
finalTx is still exposed as a convenience/safety handle for consumers that need the semantic final action (action.type, built tx metadata, guard when not previewable), but it is no longer the main way to submit calls. The main submission surface is callRequests.

Vaults-app transaction-context sketch:

const txPlan = vault.deposit({ amount, nativeAmount, userAddress, vaultData });
const prepared = await txPlan.prepare({ requestOptions: { useSimplePermit } });

const txFlowType = prepared.flowKind === "single_call"
  ? "simple"
  : prepared.signatureRequests.length > 0
    ? "signature_required"
    : "bundled";

const stepLabels = prepared.steps.map((step) => {
  switch (step.intent.type) {
    case "tokenApproval":
      return step.intent.method === "tx"
        ? `Approve ${formatAmount(step.intent.amount, token)}`
        : `Sign ${step.intent.method === "permit2" ? "Permit2" : "permit"}`;
    case "operatorAuthorization":
      return step.intent.method === "tx" ? "Authorize operator" : "Sign authorization";
    case "contractCall":
      return actionLabels[step.intent.actionType] ?? "Review transaction";
    case "midnightOfferRootSignature":
      return "Sign offer root";
    case "finalTransaction":
      return actionLabels[step.intent.actionType] ?? "Submit transaction";
  }
});

const signatures = await prepared.signAll(walletClient, userAddress);
const callsForSimulation = prepared.build(signatures).callRequests.map((step) => step.call);

Markets-app action-flow sketch:

const txPlan = midnight.supplyCollateral(params); // already a TransactionPlan
const prepared = await txPlan.prepare();
const signatures: RequirementSignature[] = [];

const signatureRequests = prepared.signatureRequests.map((step) => ({
  label: labelStep(step),
  sign: async (client) => {
    const signature = await step.sign(client, accountAddress);
    signatures.push(signature);
    return "signature" in signature.args ? signature.args.signature : "0x";
  },
}));

const callRequests = prepared.callRequests.map((step) => ({
  label: labelStep(step),
  getCall: () => step.call,
}));

// Maker flows whose final mempool-submit call depends on the collected signature
// have no unsigned preview, so the final call is produced lazily after signing.
if (!prepared.hasFinalTxPreview) {
  callRequests.push({
    label: "Submit transaction",
    getCall: () =>
      prepared.build(signatures.length > 0 ? signatures : undefined).callRequests.at(-1)!.call,
  });
}

function labelStep(step: TransactionPlanStep) {
  switch (step.intent.type) {
    case "tokenApproval":
      return step.intent.method === "tx" ? "Approve token" : "Sign token approval";
    case "operatorAuthorization":
      return step.intent.method === "tx" ? "Authorize operator" : "Sign authorization";
    case "midnightOfferRootSignature":
      return "Sign offer root";
    case "contractCall":
      return actionLabels[step.intent.actionType] ?? "Review transaction";
    case "finalTransaction":
      return actionLabels[step.intent.actionType] ?? "Submit transaction";
  }
}

Verification:

pnpm --filter @morpho-org/morpho-sdk build
pnpm lint:ci
MAINNET_RPC_URL="https://rpc.morpho.dev/cache/evm/1?secret=$RPC_SECRET" pnpm exec vitest run --project morpho-sdk packages/morpho-sdk/src/transactionPlan/TransactionPlan.test.ts packages/morpho-sdk/src/entities/vaultV1/vaultV1.test.ts packages/morpho-sdk/src/entities/vaultV2/vaultV2.test.ts packages/morpho-sdk/src/entities/blue/blue.test.ts packages/morpho-sdk/src/entities/midnight/midnight.test.ts

Requested by: <@U03L0SC1JUR>

devin-ai-integration

Devin Review found 1 potential issue.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7da4dd011c

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Rubilmax · 2026-07-08T12:28:36Z

@codex

chatgpt-codex-connector · 2026-07-08T12:34:04Z

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: 45e79af5de

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Rubilmax

almost lgtm

The base branch was changed.

Adapt the latest Midnight flows and fork tests to TransactionPlan.

…an-v1 # Conflicts: # .changeset/quiet-midnight-flows.md # packages/morpho-sdk/src/entities/blue/blue.refinance.test.ts # packages/morpho-sdk/src/entities/blue/blue.ts # packages/morpho-sdk/src/entities/midnight/midnight.test.ts # packages/morpho-sdk/src/entities/vaultV1/vaultV1.ts # packages/morpho-sdk/src/entities/vaultV2/vaultV2.ts # packages/morpho-sdk/test/actions/blue/reallocations.test.ts # packages/morpho-sdk/test/actions/wrap.test.ts

Rubilmax · 2026-07-17T08:25:26Z

              },
            },
-          },
+          } as unknown as PermitRequirementSignature,


can we get rid of this casting?

Not without making the test less explicit: expiration is required by PermitRequirementSignature, and this test intentionally constructs malformed runtime input to exercise the defensive guard. We could start from a valid typed signature and use Reflect.deleteProperty to avoid the cast, but that only hides the same type violation behind mutation. I would keep the narrow test-only cast; otherwise we should remove the runtime guard and this test if we consider the state unreachable.

Rubilmax · 2026-07-17T09:23:28Z

@codex

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6180966891

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Rubilmax · 2026-07-17T09:47:54Z

@codex

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1a1a14cfcb

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Rubilmax · 2026-07-17T10:38:41Z

@codex

chatgpt-codex-connector · 2026-07-17T10:44:30Z

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: f68ec9eba6

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

…an-v1 # Conflicts: # packages/morpho-sdk/README.md

Rubilmax

Parallel PR Review (Codex)

Reviewed commit: 5a5c40b

Severity	Count
Critical	1
High	3
Medium	3
Low	2

This is an automated parallel review.

Rubilmax · 2026-07-17T14:26:55Z


 ```ts
-export type CallRequirementAction =
+export type TxRequirementAction =


Medium: While this section is being updated for TxRequirement, the now-Accepted TIB's preceding “Requirement aliases” block still specifies the removed SignatureRequirementAction / RequirementSignatureArgs unions and obsolete two-parameter Requirement<TAction, TArgs> / RequirementSignature<TAction, TArgs> API. The implemented v6 surface correlates signatures through Requirement<TSignature> and the RequirementSignature discriminated union, so those snippets no longer compile. Rewrite that block to match the exported types.

Rubilmax · 2026-07-17T14:26:55Z

-// then calls buildTx to get the final transaction:
-const tx = buildTx([permitSignature]);
+// Or convert the executable transactions for an EIP-5792 wallet batch.
+await walletClient.sendCalls({ calls: executable.calls });


High: The copy-pasteable usage block first submits every executable.txSteps transaction individually and then immediately submits the same calls again with sendCalls. Although the comment says “Or,” both statements execute sequentially, so copying the example can double-submit the primary financial action. Put the sequential and EIP-5792 paths in mutually exclusive branches or separate code blocks.

Rubilmax · 2026-07-17T14:26:55Z

 export * from "./actions/index.js";
 export * from "./client/index.js";
 export * from "./helpers/index.js";
+export * from "./transactionPlan/index.js";


High: This public migration replaces the entity { buildTx, getRequirements } API with TransactionPlan, but the canonical docs/jsdoc-style.md exemplar still destructures buildTx from market.borrow(...) and calls it. That example no longer compiles and is explicitly the template contributors are told to copy. Update the canonical exemplar to use plan.prepare(), collect signature requests, and call prepared.build(...).

Rubilmax · 2026-07-17T14:26:55Z

+   * @returns A prepared plan whose request types and primary action match this plan.
+   * @example
+   * ```ts
+   * const prepared = await vault.deposit(params).prepare({


Low: The new public prepare() method's @example is only a fragment using undefined vault and params; it has no imports/client setup and does not show the return type. This fails the runnable-recipe requirements in docs/jsdoc-style.md. Replace it with a self-contained example using named addresses/constants, client setup, one call, and the expected PreparedTransactionPlan shape.

Rubilmax · 2026-07-17T14:26:55Z

+   * const calls = prepared.calls;
+   * ```
+   */
+  get calls(): readonly TransactionPlanBatchCall[] {


Medium: The new plan classes implement class-specific derivation directly instead of delegating to pure object-compatible utilities: calls, flowKind, hasIntent, and findIntent live on PreparedTransactionPlan, and the calls mapping is duplicated on ExecutableTransactionPlan. This violates the AGENTS.md §1 class/API convention and creates multiple sources of truth. Move these derivations into pure TransactionPlanUtils functions over readonly plan shapes and delegate the class methods/getters to them.

Rubilmax · 2026-07-17T14:26:55Z

+  ): ExecutableTransactionPlan<TPrimaryAction, TRequest> {
+    const expected = this.signatureRequests.length;
+    const received = signatures?.length ?? 0;
+    if (received !== expected) {


High: build() validates only the number of supplied signatures, not that each signature matches the prepared request. Combined Blue plans accept both permit and authorization types, so if prepare() requests only authorization but the caller supplies one permit (or vice versa), the count passes and the primary builder emits a bundle without the actually required setAuthorizationWithSig or permit action, causing the Morpho operation to revert. Bind each signature to the corresponding prepared request/action type and add a same-count wrong-kind regression test.

Rubilmax · 2026-07-17T14:26:55Z

+ * for (const step of executable.txSteps) {
+ *   await walletClient.sendTransaction(step.tx);
+ * }
+ * await walletClient.sendCalls({ calls: executable.calls });


Critical: This public executable-plan example submits every transaction twice: first individually via sendTransaction, then again as the full sendCalls batch. Copying it can duplicate deposits, borrows, or other fund-moving primary actions. Present these as mutually exclusive execution alternatives, as separate branches or code blocks.

Rubilmax · 2026-07-17T14:26:55Z

+   * });
+   * ```
+   */
+  constructor(


Medium: The exported constructor accepts primaryStep and txSteps independently without ensuring the same primary step is last in txSteps. Consumers can construct an instance whose primaryStep / primaryTx disagree with txSteps / calls, breaking the advertised invariant. Keep construction internal/private or validate and centralize it behind a static factory.

Rubilmax · 2026-07-17T14:26:55Z

+    public readonly received: number,
+  ) {
+    super(
+      `Expected exactly ${expected} transaction-plan signatures but received ${received}. Pass one signature for each prepared signature request and no others.`,


Low: The new error message interpolates expected and received without quotes, contrary to AGENTS.md §3's required quoted formatting for interpolated values. Format the values as expected "${expected}", got "${received}" (while retaining the actionable guidance).

prd-carapulse Bot requested a review from a team as a code owner July 8, 2026 08:10

devin-ai-integration Bot reviewed Jul 8, 2026

View reviewed changes

Comment thread packages/morpho-sdk/src/transactionPlan.ts Outdated

chatgpt-codex-connector Bot reviewed Jul 8, 2026

View reviewed changes

Comment thread packages/morpho-sdk/src/transactionPlan.ts Outdated

Comment thread packages/morpho-sdk/src/transactionPlan.ts Outdated

Rubilmax reviewed Jul 8, 2026

View reviewed changes

Comment thread packages/morpho-sdk/src/transactionPlan.ts Outdated

Comment thread packages/morpho-sdk/src/transactionPlan.ts Outdated

Comment thread packages/morpho-sdk/src/transactionPlan.ts Outdated

Rubilmax self-assigned this Jul 8, 2026

Rubilmax reviewed Jul 8, 2026

View reviewed changes

Comment thread packages/morpho-sdk/src/helpers/transactionPlan.ts Outdated

prd-carapulse Bot force-pushed the hermes/transaction-plan branch 2 times, most recently from 71e53b9 to 93a73c1 Compare July 9, 2026 08:38

prd-carapulse Bot changed the base branch from main to hermes/marketv2-action-flows-implementation July 9, 2026 08:38

Rubilmax reviewed Jul 9, 2026

View reviewed changes

Comment thread packages/morpho-sdk/src/entities/blue/blue.ts Outdated

Comment thread packages/morpho-sdk/src/entities/vaultV1/vaultV1.ts Outdated

Rubilmax reviewed Jul 10, 2026

View reviewed changes

Comment thread packages/morpho-sdk/src/transactionPlan/types.ts Outdated

Rubilmax force-pushed the hermes/marketv2-action-flows-implementation branch from 0a07ac8 to 50c0fee Compare July 13, 2026 09:39

Rubilmax force-pushed the hermes/transaction-plan branch from e63799a to 9d7fdef Compare July 13, 2026 09:52

prd-carapulse Bot force-pushed the hermes/transaction-plan branch from 9d7fdef to faf9ffc Compare July 14, 2026 21:40

Rubilmax previously approved these changes Jul 15, 2026

View reviewed changes

Rubilmax force-pushed the hermes/transaction-plan branch 4 times, most recently from bec7c22 to 962e29d Compare July 16, 2026 07:47

Rubilmax force-pushed the hermes/marketv2-action-flows-implementation branch from 0321d43 to 91d57a6 Compare July 16, 2026 09:19

Base automatically changed from hermes/marketv2-action-flows-implementation to main July 16, 2026 09:32

Rubilmax added 5 commits July 16, 2026 11:41

feat(morpho-sdk): add transaction plan

8ea3e0c

Adapt the latest Midnight flows and fork tests to TransactionPlan.

fix: correct transaction plan release notes and WDK typing

964d38c

fix: update transaction plan package metadata

86dce41

fix(morpho-sdk): address transaction plan review

29c934e

fix(morpho-sdk): update transaction plan docs and signature types

aa08791

Rubilmax force-pushed the hermes/transaction-plan branch from b5e42cc to aa08791 Compare July 16, 2026 09:47

Rubilmax reviewed Jul 16, 2026

View reviewed changes

Comment thread packages/morpho-sdk/test/transactionPlanUtils.ts Outdated

Rubilmax added 3 commits July 17, 2026 10:06

refactor(morpho-sdk): simplify transaction plan API

c2caf1d

refactor(morpho-sdk): shorten transaction plan tx names

131256d

Rubilmax reviewed Jul 17, 2026

View reviewed changes

Rubilmax added 2 commits July 17, 2026 11:01

refactor(morpho-sdk): strengthen transaction plan signature types

7bb2801

test(morpho-sdk): inspect prepared vault transactions

6180966

chatgpt-codex-connector Bot reviewed Jul 17, 2026

View reviewed changes

Comment thread packages/morpho-sdk/src/transactionPlan/TransactionPlan.ts Outdated

fix(morpho-sdk): reject surplus plan signatures

1a1a14c

chatgpt-codex-connector Bot reviewed Jul 17, 2026

View reviewed changes

Comment thread packages/morpho-sdk/src/entities/midnight/midnight.ts Outdated

Comment thread packages/morpho-sdk/src/client/morphoViemExtension.ts Outdated

Comment thread packages/wdk-protocol-lending-morpho-evm/src/morpho-protocol-evm.ts

Rubilmax added 2 commits July 17, 2026 12:09

test(morpho-sdk): prepare Midnight offer signatures

bcce335

fix: use transaction plan previews where available

f68ec9e

Merge remote-tracking branch 'origin/main' into hermes/transaction-pl…

5a5c40b

…an-v1 # Conflicts: # packages/morpho-sdk/README.md

Rubilmax reviewed Jul 17, 2026

View reviewed changes

Uh oh!

Conversation

prd-carapulse Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Rubilmax commented Jul 8, 2026

Uh oh!

Uh oh!

chatgpt-codex-connector Bot commented Jul 8, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Rubilmax left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Rubilmax commented Jul 17, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Rubilmax commented Jul 17, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Rubilmax commented Jul 17, 2026

Uh oh!

chatgpt-codex-connector Bot commented Jul 17, 2026

Uh oh!

Rubilmax left a comment

Choose a reason for hiding this comment

Parallel PR Review (Codex)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

prd-carapulse Bot commented Jul 8, 2026 •

edited

Loading