feat(transaction-controller): add approval-time sponsorship/signing hooks

[pedronfigueiredo]

Related pull requests

• Extension: MetaMask/metamask-extension#46060
• Mobile: MetaMask/metamask-mobile#35754

Summary

• Add optional approval-time isSponsored and shouldSign hooks to TransactionController, with named object results for future extensibility.
• Default omitted hooks to non-sponsored transactions with local signing.
• Deprecate the legacy isGasFeeSponsored and isExternalSign lifecycle properties while retaining them in public types for compatibility; isGasFeeSponsored remains available as migration metadata.
• When simulation is enabled, refresh gas-fee-token and sponsorship availability after approval preparation and expose it as TransactionMeta.isGasFeeSponsoredAvailable before sponsorship policy runs.
• Reserve a nonce and sign locally only for non-sponsored transactions when shouldSign returns true.
• Preserve existing nonces when local signing is skipped and include newly reserved nonces in the approved status event.
• Require a client publish hook when local signing is skipped. Unsigned publication is owned by that hook, and the controller does not fall back to eth_sendRawTransaction with an empty payload or require the hook to return a transaction hash.

Public API

hooks?: {
  afterAdd?: AfterAddHook;
  beforeCheckPendingTransaction?: (
    transactionMeta: TransactionMeta,
  ) => Promise<boolean>;
  beforePublish?: (
    transactionMeta: TransactionMeta,
  ) => Promise<boolean>;
  beforeSign?: BeforeSignHook;
  isSponsored?: (request: {
    transactionMeta: TransactionMeta;
  }) => Promise<{ isSponsored: boolean }>;
  publish?: (
    transactionMeta: TransactionMeta,
  ) => Promise<{ transactionHash: string }>;
  publishBatch?: PublishBatchHook;
  shouldSign?: (request: {
    transactionMeta: TransactionMeta;
  }) => Promise<{ shouldSign: boolean }>;
}

The new hooks are optional. Without them, transactions retain the existing non-sponsored, locally signed behavior.

Approval behavior

1. Mark the transaction as approved and run beforeSign preparation.
2. Run the extracted approval-preparation helper, which refreshes gas-fee tokens and isGasFeeSponsoredAvailable when simulation is enabled (or selected-token preflight requires it), then performs the gas-fee-token preflight.
3. Call isSponsored (default: false).
4. If sponsored, skip shouldSign, nonce reservation, and local signing.
5. Otherwise call shouldSign (default: true); reserve a nonce and sign only when it returns true.
6. Publish the approved status after any local nonce reservation, then continue through signing and publication.
7. If local signing is skipped, require and defer to a publish hook. Do not invoke the provider fallback with the unsigned 0x sentinel; the hook may return without a transaction hash.

beforeSign always runs, including when local signing is skipped. Existing nonces are retained on externally prepared transactions. Hook outcomes are transient policy results and are not persisted as transaction metadata.

Validation

• yarn workspace @metamask/transaction-controller run test
• yarn workspace @metamask/transaction-controller run build
• yarn eslint <changed TypeScript files>
• yarn prettier --check <changed TypeScript files>
• yarn changelog:validate

The package test suite, package build, focused ESLint, changed-TypeScript formatting checks, changelog validation, and branch diff check pass.

---

Note

High Risk
Breaking changes to core transaction approval, nonce, signing, and publish behavior affect every client that relied on deprecated sponsorship/external-sign metadata or simulation-driven sponsorship.

Overview
Breaking: Sponsorship and local signing are no longer driven by isGasFeeSponsored, isExternalSign, or simulation’s old isGasFeeSponsored flag. Integrators must use optional approval-time isSponsored and shouldSign hooks (defaults: not sponsored, sign locally).

On approval, the controller runs beforeSign, refreshes gas-fee tokens and sets TransactionMeta.isGasFeeSponsoredAvailable when simulation (or token preflight) requires it, then evaluates the hooks. Sponsored flows skip shouldSign, nonce reservation, and local signing. When shouldSign is false, existing nonces are kept, beforeSign still runs, and publication requires a publish hook—the controller will not fall back to eth_sendRawTransaction with an empty payload.

Simulation/gas-fee helpers now expose sponsorship availability (isGasFeeSponsoredAvailable) instead of treating simulation as the lifecycle policy. Legacy fields remain on types as deprecated migration metadata only. Tests and changelog document the new behavior, including batch gas-fee poller updates and stricter publish paths.

^{Reviewed by Cursor Bugbot for commit 71e88f2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 83fe8f8. Configure here.}