feat(morpho-sdk): add transaction plan

[prd-carapulse]

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]

@codex

[chatgpt-codex-connector]

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