@metamask/transaction-pay-controller 24.0.2 → 24.1.0

package/dist/strategy/server/server-submit.mjs

@@ -1,12 +1,29 @@
-import { ORIGIN_METAMASK, toHex } from "@metamask/controller-utils";
+import { ORIGIN_METAMASK, successfulFetch, toHex } from "@metamask/controller-utils";
+import { SignTypedDataVersion } from "@metamask/keyring-controller";
 import { createModuleLogger } from "@metamask/utils";
 import { BigNumber } from "bignumber.js";
 import { projectLogger } from "../../logger.mjs";
 import { getServerPollingInterval, getServerPollingTimeout } from "../../utils/feature-flags.mjs";
+import { getNetworkClientId } from "../../utils/provider.mjs";
+import { getLiveTokenBalance, normalizeTokenAddress, TokenAddressTarget } from "../../utils/token.mjs";
 import { collectTransactionIds, getTransaction, updateTransaction, waitForTransactionConfirmed } from "../../utils/transaction.mjs";
+import { RELAY_DEPOSIT_TYPES } from "../relay/constants.mjs";
 import { getServerStatus, submitServerIntent } from "./server-api.mjs";
 import { ServerStatus } from "./types.mjs";
 const log = createModuleLogger(projectLogger, 'server-strategy');
+const DOMAIN_FIELD_MAP = {
+    name: { name: 'name', type: 'string' },
+    version: { name: 'version', type: 'string' },
+    chainId: { name: 'chainId', type: 'uint256' },
+    verifyingContract: { name: 'verifyingContract', type: 'address' },
+    salt: { name: 'salt', type: 'bytes32' },
+};
+function isSignatureStep(step) {
+    return step.type === 'signature';
+}
+function isTransactionStep(step) {
+    return step.type === 'transaction';
+}
 /**
  * Submits server intent quotes.
  *
@@ -31,12 +48,15 @@ async function executeSingleServerQuote(quote, messenger, transaction) {
     }, (tx) => {
         tx.txParams.nonce = undefined;
     });
-    if (quote.original.gasless) {
-        await submitViaServerExecute(quote, messenger, transaction);
-    }
-    else {
-        await submitViaTransactionController(quote, messenger, transaction);
+    // Phase 1: off-chain signature steps (e.g. Relay authorize, HyperLiquid deposit).
+    // Use quote.request.from (resolved accountOverride) not transaction.txParams.from.
+    const signatureSteps = quote.original.steps.filter(isSignatureStep);
+    for (const step of signatureSteps) {
+        await submitSignatureStep(step, quote.request.from, messenger);
     }
+    // Phase 2: on-chain transaction steps (if any).
+    await submitTransactionSteps(quote, messenger, transaction);
+    // Phase 3: poll until the intent is confirmed on the target chain.
     const targetHash = await waitForServerCompletion(quote.original, messenger, transaction.id);
     log('Server request completed', targetHash);
     updateTransaction({
@@ -48,13 +68,299 @@ async function executeSingleServerQuote(quote, messenger, transaction) {
     });
     return { transactionHash: targetHash };
 }
-async function submitViaServerExecute(quote, messenger, transaction) {
-    const { from, sourceChainId } = quote.request;
-    const networkClientId = messenger.call('NetworkController:findNetworkClientIdByChainId', sourceChainId);
-    const nestedTransactions = quote.original.steps.map((step) => ({
+/**
+ * Submit the on-chain transaction steps for a server quote.
+ *
+ * Validates the source balance, builds the complete set of params (including
+ * any post-quote or payment-override prepends), then dispatches to the
+ * gasless execute path or TransactionController depending on the quote.
+ *
+ * No-ops when the quote has no transaction steps (signature-only flows).
+ *
+ * @param quote - Server quote.
+ * @param messenger - Controller messenger.
+ * @param transaction - Original transaction meta.
+ */
+async function submitTransactionSteps(quote, messenger, transaction) {
+    const transactionSteps = quote.original.steps.filter(isTransactionStep);
+    if (transactionSteps.length === 0) {
+        // Signature-only quotes (all steps are signature steps, no transaction
+        // steps) have nothing to submit on-chain even when gasless is false.
+        const hasSignatureSteps = quote.original.steps.some(isSignatureStep);
+        if (!quote.original.gasless && !hasSignatureSteps) {
+            throw new Error('Server quote has no steps to submit');
+        }
+        return;
+    }
+    const { isHyperliquidSource, isPostQuote, paymentOverride } = quote.request;
+    // Skip balance check for HyperLiquid source flows (no on-chain debit),
+    // post-quote flows (funds come from the Safe after the original tx executes),
+    // and payment-override flows (funds are supplied by the override account).
+    if (!isHyperliquidSource && !isPostQuote && !paymentOverride) {
+        await validateSourceBalance(quote, messenger);
+    }
+    const allParams = await buildTransactionParams(quote, transactionSteps, transaction, messenger);
+    if (quote.original.gasless) {
+        await submitViaServerExecute(quote, allParams, messenger, transaction);
+    }
+    else {
+        await submitViaTransactionController(quote, allParams, messenger, transaction);
+    }
+}
+/**
+ * Build the complete flat array of TransactionParams for on-chain submission.
+ *
+ * Converts server transaction steps to params, then prepends any additional
+ * calls required by the payment override or post-quote flow. The returned
+ * array is ready to pass directly to submitViaServerExecute or
+ * submitViaTransactionController.
+ *
+ * @param quote - Server quote.
+ * @param transactionSteps - Transaction steps from the quote (pre-filtered).
+ * @param transaction - Original transaction meta.
+ * @param messenger - Controller messenger.
+ * @returns Complete ordered array of TransactionParams for submission.
+ */
+async function buildTransactionParams(quote, transactionSteps, transaction, messenger) {
+    const { from, isPostQuote, paymentOverride } = quote.request;
+    const { gasLimits, maxFeePerGas, maxPriorityFeePerGas } = quote.original.client;
+    const originalType = getEffectiveTransactionType(transaction);
+    const relayParams = transactionSteps.map((step, i) => transactionStepToParams(step, i, transactionSteps.length, from, gasLimits, maxFeePerGas, maxPriorityFeePerGas, originalType));
+    if (paymentOverride) {
+        return prependPaymentOverrideParams(relayParams, quote, transaction, messenger);
+    }
+    if (isPostQuote && transaction.txParams.to) {
+        return prependPostQuoteParams(relayParams, quote, transaction, messenger);
+    }
+    return relayParams;
+}
+/**
+ * Converts a single server transaction step to TransactionParams.
+ *
+ * @param step - The transaction step.
+ * @param index - Zero-based position within the transaction steps array.
+ * @param totalSteps - Total number of transaction steps (for type mapping).
+ * @param from - Sender address.
+ * @param gasLimits - Per-step gas limits from client-side estimation.
+ * @param clientMaxFeePerGas - Client-side max fee per gas fallback.
+ * @param clientMaxPriorityFeePerGas - Client-side max priority fee per gas fallback.
+ * @param originalType - Effective type of the parent transaction.
+ * @returns Normalized TransactionParams for this step.
+ */
+function transactionStepToParams(step, index, totalSteps, from, gasLimits, clientMaxFeePerGas, clientMaxPriorityFeePerGas, originalType) {
+    let gas;
+    const gasLimit = gasLimits[index];
+    if (gasLimit) {
+        gas = toHex(gasLimit);
+    }
+    else if (step.gasLimit) {
+        gas = toHex(step.gasLimit);
+    }
+    const resolvedMaxFeePerGas = step.maxFeePerGas ?? clientMaxFeePerGas;
+    const resolvedMaxPriorityFeePerGas = step.maxPriorityFeePerGas ?? clientMaxPriorityFeePerGas;
+    const params = {
         data: step.data,
+        from,
+        gas,
+        maxFeePerGas: resolvedMaxFeePerGas
+            ? toHex(resolvedMaxFeePerGas)
+            : undefined,
+        maxPriorityFeePerGas: resolvedMaxPriorityFeePerGas
+            ? toHex(resolvedMaxPriorityFeePerGas)
+            : undefined,
         to: step.to,
-        value: step.value,
+        type: getTransactionType(index, totalSteps, originalType),
+        value: toHex(step.value),
+    };
+    log('Built transaction params for step', {
+        index,
+        step: {
+            gasLimit: step.gasLimit,
+            maxFeePerGas: step.maxFeePerGas,
+            maxPriorityFeePerGas: step.maxPriorityFeePerGas,
+            value: step.value,
+        },
+        params: {
+            gas: params.gas,
+            maxFeePerGas: params.maxFeePerGas,
+            maxPriorityFeePerGas: params.maxPriorityFeePerGas,
+            type: params.type,
+            value: params.value,
+        },
+    });
+    return params;
+}
+/**
+ * Determine the relay deposit transaction type for a step at the given index.
+ *
+ * Single-step quotes always use the deposit type. In multi-step quotes the
+ * first step is an approval and subsequent steps are deposits — matching the
+ * Relay strategy's convention.
+ *
+ * @param index - Zero-based index of the step within the transaction step array.
+ * @param totalSteps - Total number of transaction steps.
+ * @param originalType - Effective type of the parent transaction.
+ * @returns The mapped TransactionType for this step.
+ */
+function getTransactionType(index, totalSteps, originalType) {
+    const depositType = getRelayDepositType(originalType);
+    if (totalSteps === 1) {
+        return depositType;
+    }
+    return index === 0 ? 'tokenMethodApprove' : depositType;
+}
+/**
+ * Get the relay deposit transaction type based on the parent transaction type.
+ *
+ * @param originalType - Type of the parent transaction.
+ * @returns The mapped relay deposit type, or `relayDeposit` as a fallback.
+ */
+function getRelayDepositType(originalType) {
+    return ((originalType && RELAY_DEPOSIT_TYPES[originalType]) ??
+        'relayDeposit');
+}
+/**
+ * Get the effective transaction type, resolving through batch-type parent
+ * transactions to find the nested perps/predict type.
+ *
+ * @param transaction - The transaction metadata.
+ * @returns The resolved type from nested transactions, or the top-level type.
+ */
+function getEffectiveTransactionType(transaction) {
+    if (transaction.type !== 'batch') {
+        return transaction.type;
+    }
+    const nestedType = transaction.nestedTransactions?.find((tx) => tx.type && RELAY_DEPOSIT_TYPES[tx.type] !== undefined)?.type;
+    return nestedType ?? transaction.type;
+}
+/**
+ * Prepend payment override calls before the relay transaction steps.
+ *
+ * For money-account payment override flows the override account supplies
+ * the source funds. The override transactions must be batched ahead of the
+ * relay deposit steps.
+ *
+ * @param relayParams - Already-built relay step params.
+ * @param quote - Server quote.
+ * @param transaction - Original transaction meta.
+ * @param messenger - Controller messenger.
+ * @returns Combined params with override calls prepended.
+ */
+async function prependPaymentOverrideParams(relayParams, quote, transaction, messenger) {
+    const { transactionData } = messenger.call('TransactionPayController:getState');
+    const { calls: overrideCalls } = await messenger.call('TransactionPayController:getPaymentOverrideData', {
+        amount: quote.sourceAmount.human,
+        transaction,
+        transactionData: transactionData[transaction.id],
+    });
+    if (!overrideCalls.length) {
+        log('No payment override calls to prepend');
+        return relayParams;
+    }
+    log('Prepending payment override calls', { count: overrideCalls.length });
+    return [...overrideCalls, ...relayParams];
+}
+/**
+ * Prepend the original transaction (or a delegation-wrapped version) before
+ * the relay deposit steps for post-quote flows.
+ *
+ * In post-quote flows the source tokens are held in the Safe and only become
+ * available after the original transaction executes as part of the batch.
+ * When an accountOverride is active the override account cannot directly
+ * execute the original call, so it is wrapped in a delegation transaction.
+ *
+ * @param relayParams - Already-built relay step params.
+ * @param quote - Server quote.
+ * @param transaction - Original transaction meta.
+ * @param messenger - Controller messenger.
+ * @returns Combined params with the original tx prepended.
+ */
+async function prependPostQuoteParams(relayParams, quote, transaction, messenger) {
+    const hasAccountOverride = quote.request.from.toLowerCase() !==
+        transaction.txParams.from.toLowerCase();
+    const { maxFeePerGas, maxPriorityFeePerGas } = quote.original.client;
+    let prependedParams;
+    if (hasAccountOverride) {
+        prependedParams = await buildDelegatedOriginalParams(transaction, messenger);
+    }
+    else {
+        prependedParams = {
+            data: transaction.txParams.data,
+            from: transaction.txParams.from,
+            to: transaction.txParams.to,
+            value: transaction.txParams.value,
+        };
+    }
+    // Ensure the prepended tx carries the same fee caps as the relay steps so
+    // it isn't submitted with undefined maxFeePerGas in a non-7702 batch.
+    prependedParams.maxFeePerGas = maxFeePerGas ? toHex(maxFeePerGas) : undefined;
+    prependedParams.maxPriorityFeePerGas = maxPriorityFeePerGas
+        ? toHex(maxPriorityFeePerGas)
+        : undefined;
+    log('Prepending post-quote original tx', { hasAccountOverride });
+    return [prependedParams, ...relayParams];
+}
+/**
+ * Build TransactionParams for a delegation that redeems the original
+ * post-quote transaction on behalf of the override account.
+ *
+ * @param transaction - Original transaction meta to be redeemed.
+ * @param messenger - Controller messenger.
+ * @returns Transaction params for the delegation tx.
+ */
+async function buildDelegatedOriginalParams(transaction, messenger) {
+    const delegation = await messenger.call('TransactionPayController:getDelegationTransaction', { transaction });
+    log('Delegation result for post-quote original tx', delegation);
+    return {
+        data: delegation.data,
+        from: transaction.txParams.from,
+        to: delegation.to,
+        value: delegation.value,
+    };
+}
+/**
+ * Validate that the user's source token balance covers the quote's required
+ * source amount before submitting on-chain.
+ *
+ * Reads the live balance via RPC rather than the cached state so it reflects
+ * any concurrent spends. Throws fast with a clear error instead of letting
+ * the on-chain transaction revert.
+ *
+ * @param quote - Server quote containing the required source amount.
+ * @param messenger - Controller messenger.
+ */
+async function validateSourceBalance(quote, messenger) {
+    const { from, sourceChainId, sourceTokenAddress } = quote.request;
+    const normalizedSourceTokenAddress = normalizeTokenAddress(sourceTokenAddress, sourceChainId, TokenAddressTarget.MetaMask);
+    let currentBalance;
+    try {
+        currentBalance = await getLiveTokenBalance(messenger, from, sourceChainId, normalizedSourceTokenAddress);
+    }
+    catch (error) {
+        throw new Error(`Cannot validate payment token balance - ${error.message}`);
+    }
+    const requiredAmount = new BigNumber(quote.sourceAmount.raw);
+    const balance = new BigNumber(currentBalance);
+    log('Validating source balance', {
+        from,
+        sourceChainId,
+        sourceTokenAddress,
+        currentBalance,
+        requiredAmount: requiredAmount.toString(10),
+    });
+    if (balance.isLessThan(requiredAmount)) {
+        throw new Error(`Insufficient source token balance for server deposit. ` +
+            `Required: ${requiredAmount.toString(10)}, ` +
+            `Available: ${balance.toString(10)}`);
+    }
+}
+async function submitViaServerExecute(quote, allParams, messenger, transaction) {
+    const { from, sourceChainId } = quote.request;
+    const networkClientId = getNetworkClientId(messenger, sourceChainId);
+    const nestedTransactions = allParams.map((params) => ({
+        data: (params.data ?? '0x'),
+        to: params.to,
+        value: (params.value ?? '0x0'),
     }));
     const sourceCallTransaction = {
         ...transaction,
@@ -93,15 +399,10 @@ async function submitViaServerExecute(quote, messenger, transaction) {
         throw new Error(`Server submit failed: ${submitResponse.error ?? 'unknown'}`);
     }
 }
-async function submitViaTransactionController(quote, messenger, transaction) {
+async function submitViaTransactionController(quote, allParams, messenger, transaction) {
     const { from, sourceChainId, sourceTokenAddress } = quote.request;
-    const { steps } = quote.original;
-    if (steps.length === 0) {
-        throw new Error('Server quote has no steps to submit');
-    }
-    const networkClientId = messenger.call('NetworkController:findNetworkClientIdByChainId', sourceChainId);
-    const { gasLimits, is7702, maxFeePerGas, maxPriorityFeePerGas } = quote.original.client;
-    const transactionParams = steps.map((step, i) => stepToParams(step, from, gasLimits[i], maxFeePerGas, maxPriorityFeePerGas));
+    const { gasLimits, is7702 } = quote.original.client;
+    const networkClientId = getNetworkClientId(messenger, sourceChainId);
     const gasFeeToken = quote.fees.isSourceGasFeeToken
         ? sourceTokenAddress
         : undefined;
@@ -110,8 +411,8 @@ async function submitViaTransactionController(quote, messenger, transaction) {
         gasFeeToken,
         is7702,
         networkClientId,
+        paramCount: allParams.length,
         sourceChainId,
-        stepCount: steps.length,
     });
     const transactionIds = [];
     const { end } = collectTransactionIds(sourceChainId, from, messenger, (transactionId) => {
@@ -126,7 +427,7 @@ async function submitViaTransactionController(quote, messenger, transaction) {
         });
     });
     try {
-        if (transactionParams.length === 1) {
+        if (allParams.length === 1) {
             const addTransactionOptions = {
                 gasFeeToken,
                 isInternal: true,
@@ -135,16 +436,19 @@ async function submitViaTransactionController(quote, messenger, transaction) {
                 requireApproval: false,
             };
             log('Calling addTransaction', {
-                params: transactionParams[0],
+                params: allParams[0],
                 options: addTransactionOptions,
             });
-            await messenger.call('TransactionController:addTransaction', transactionParams[0], addTransactionOptions);
+            await messenger.call('TransactionController:addTransaction', allParams[0], addTransactionOptions);
         }
         else {
             const gasLimit7702 = is7702 ? toHex(gasLimits[0]) : undefined;
-            const batchTransactions = transactionParams.map((params, i) => {
-                const gas = (gasLimit7702 ??
-                    (gasLimits[i] === undefined ? undefined : params.gas));
+            const batchTransactions = allParams.map((params) => {
+                // params.gas was already resolved correctly by transactionStepToParams
+                // (indexed by relay-step position), so use it directly. Indexing
+                // allParams position into gasLimits would be wrong when payment-
+                // override or post-quote params are prepended.
+                const gas = (gasLimit7702 ?? params.gas);
                 return {
                     params: {
                         data: params.data,
@@ -154,6 +458,7 @@ async function submitViaTransactionController(quote, messenger, transaction) {
                         to: params.to,
                         value: params.value,
                     },
+                    type: params.type,
                 };
             });
             const addTransactionBatchOptions = {
@@ -199,44 +504,67 @@ async function submitViaTransactionController(quote, messenger, transaction) {
         });
     }
 }
-function stepToParams(step, from, gasLimit, clientMaxFeePerGas, clientMaxPriorityFeePerGas) {
-    let gas;
-    if (gasLimit) {
-        gas = toHex(gasLimit);
-    }
-    else if (step.gasLimit) {
-        gas = toHex(step.gasLimit);
-    }
-    const resolvedMaxFeePerGas = step.maxFeePerGas ?? clientMaxFeePerGas;
-    const resolvedMaxPriorityFeePerGas = step.maxPriorityFeePerGas ?? clientMaxPriorityFeePerGas;
-    const params = {
-        data: step.data,
-        from,
-        gas,
-        maxFeePerGas: resolvedMaxFeePerGas
-            ? toHex(resolvedMaxFeePerGas)
-            : undefined,
-        maxPriorityFeePerGas: resolvedMaxPriorityFeePerGas
-            ? toHex(resolvedMaxPriorityFeePerGas)
-            : undefined,
-        to: step.to,
-        value: toHex(step.value),
-    };
-    log('Step to params', {
-        step: {
-            gasLimit: step.gasLimit,
-            maxFeePerGas: step.maxFeePerGas,
-            maxPriorityFeePerGas: step.maxPriorityFeePerGas,
-            value: step.value,
-        },
-        params: {
-            gas: params.gas,
-            maxFeePerGas: params.maxFeePerGas,
-            maxPriorityFeePerGas: params.maxPriorityFeePerGas,
-            value: params.value,
+async function submitSignatureStep(step, from, messenger) {
+    const { sign, post } = step;
+    const typedData = {
+        domain: sign.domain,
+        types: {
+            ...sign.types,
+            EIP712Domain: deriveEIP712DomainType(sign.domain),
         },
+        primaryType: sign.primaryType,
+        message: sign.value,
+    };
+    log('Signing typed data for signature step', {
+        primaryType: sign.primaryType,
     });
-    return params;
+    const signature = await messenger.call('KeyringController:signTypedMessage', { from, data: JSON.stringify(typedData) }, SignTypedDataVersion.V4);
+    await postSignatureStepResult(post.endpoint, post.method, post.body, signature, post.signatureFormat);
+}
+async function postSignatureStepResult(endpoint, method, body, signature, signatureFormat) {
+    let url = endpoint;
+    let postBody;
+    if (signatureFormat === 'queryParam') {
+        url = `${endpoint}?signature=${signature}`;
+        postBody = body;
+    }
+    else {
+        // eslint-disable-next-line id-length
+        const r = signature.slice(0, 66);
+        // eslint-disable-next-line id-length
+        const s = `0x${signature.slice(66, 130)}`;
+        // eslint-disable-next-line id-length
+        const v = parseInt(signature.slice(130, 132), 16);
+        postBody = { ...body, signature: { r, s, v } };
+    }
+    log('Posting signature step result', { url, signatureFormat });
+    let result;
+    try {
+        const response = await successfulFetch(url, {
+            method,
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(postBody),
+        });
+        result = await response.json();
+    }
+    catch (error) {
+        throw new Error(`Signature step POST failed: ${error.message}`);
+    }
+    log('Signature step POST response', result);
+    // For rsv-format steps (HyperLiquid exchange endpoint) the response body
+    // carries an explicit status field. Validate it here so a failed deposit
+    // throws immediately rather than silently proceeding to the polling phase.
+    if (signatureFormat === 'rsv') {
+        const status = result?.status;
+        if (status !== 'ok') {
+            throw new Error(`Signature step rejected by server: ${JSON.stringify(result)}`);
+        }
+    }
+}
+function deriveEIP712DomainType(domain) {
+    return Object.keys(DOMAIN_FIELD_MAP)
+        .filter((key) => Object.prototype.hasOwnProperty.call(domain, key))
+        .map((key) => DOMAIN_FIELD_MAP[key]);
 }
 async function waitForServerCompletion(quote, messenger, transactionId) {
     const pollingInterval = getServerPollingInterval(messenger);