Add createx402DelegationProvider to @metamask/smart-accounts-kit/experimental

[jeffsmale90]

📝 Description

Adds createx402DelegationProvider and related utils and types to @metamask/smart-accounts-kit/experimental.

The resulting DelegationProvider can be used with the x402Erc7710Client.

Examples

Minimal provider (quick start)

Use this when you just want the specified account to create a root delegation to cover the PaymentRequirements.

import { privateKeyToAccount } from 'viem/accounts';
import { createx402DelegationProvider } from '@metamask/smart-accounts-kit/experimental';
import { x402Erc7710Client } from '@metamask/x402';

const account = privateKeyToAccount(privateKey);

const erc7710Client = new x402Erc7710Client({
  delegationProvider: createx402DelegationProvider({
    account,
  }),
});

---

Re-delegate from a static permissionContext

Use this when you already have a parent delegation and want to redelegate it.

import { createx402DelegationProvider } from '@metamask/smart-accounts-kit/experimental';

const parentPermissionContext =
  '0x...'; // previously stored/issued permission context

const delegationProvider = createx402DelegationProvider({
  account,
  parentPermissionContext,
});

---

Add a short expiration

Use this for safer, short-lived delegations (for example, 60 seconds).

import { createx402DelegationProvider } from '@metamask/smart-accounts-kit/experimental';

const delegationProvider = createx402DelegationProvider({
  account,
  expirySeconds: 60
});

Or use a dynamic expiration, specifying a shorter expiration for larger amounts.

import { createx402DelegationProvider } from '@metamask/smart-accounts-kit/experimental';

const delegationProvider = createx402DelegationProvider({
  account,
  expirySeconds: (paymentRequirements) => {
    const shortLived = BigInt(requirements.amount) > 1_000_000n;
    return shortLived ? 20 : 60;
  }
});

---

Dynamic caveats per payment requirements

Use this when caveats should depend on network, asset, amount, etc.

import {
  CaveatType,
  createx402DelegationProvider,
} from '@metamask/smart-accounts-kit/experimental';

const delegationProvider = createx402DelegationProvider({
  account,
  environment,
  caveats: async (requirements) => {
    const now = Math.floor(Date.now() / 1000);

    // Example: tighter expiry for larger amounts
    const shortLived = BigInt(requirements.amount) > 1_000_000n;

    return [
      {
        type: CaveatType.Timestamp,
        afterThreshold: now - 5,
        beforeThreshold: now + (shortLived ? 20 : 60),
      },
      // add additional caveats here based on requirements.network/asset/payTo/etc.
    ];
  },
});

---

5) Use a dynamic parent permissionContext

Use this when parent delegations are stored by chain/user/merchant and loaded at runtime.

import { createx402DelegationProvider } from '@metamask/smart-accounts-kit/experimental';

const delegationProvider = createx402DelegationProvider({
  account,
  environment,
  parentPermissionContext: async (requirements) => {
    return await loadPermissionContext({
      network: requirements.network,
      payTo: requirements.payTo,
      asset: requirements.asset,
    });
  },
});

---

6) Deterministic from and salt for reproducibility

Use this when you want stable delegation derivation, or if delegating from an account other than the specified account (i.e., a MultiSig account where account is an authorized signer).

import { getAddress } from 'viem';
import { createx402DelegationProvider } from '@metamask/smart-accounts-kit/experimental';

const delegationProvider = createx402DelegationProvider({
  account,
  environment,
  from: getAddress('0x1234...'), // explicit delegator
  salt: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
});

🚀 Why?

The x402Erc7710Client must be instantiated with a DelegationProvider. Presently the caller must implement the logic for creating the DelegationPayload.

With this new x402DelegationProvider, the caller can model most use cases without having to implement complex delegation creation and signing. The intention is to cover the vast majority of use cases, while also allowing the caller to implement the DelegationProvider themselves if needed.

⚠️ Breaking Changes

List any breaking changes:

• No breaking changes
• Breaking changes (describe below):

📋 Checklist

Check off completed items:

• Code follows the project's coding standards
• Self-review completed
• Documentation updated (if needed)
• Tests added/updated
• Changelog updated (if needed)
• All CI checks pass

🔗 Related Issues

Link to related issues:
Closes #
Related to #

📚 Additional Notes

Any additional information, concerns, or context:

---

Note

Medium Risk
New delegation creation and signing paths with automatic caveat enforcement affect payment authorization scope; logic is security-sensitive but isolated to experimental exports and covered by extensive tests.

Overview
Adds an experimental createx402DelegationProvider under @metamask/smart-accounts-kit/experimental so x402Erc7710Client callers can supply a ready-made delegation provider instead of building signed delegation payloads themselves.

For each x402 PaymentRequirements challenge, the provider resolves static or deferred config (account, environment, caveats, parent permissionContext, from/salt, redeemer rules, optional expirySeconds), builds an open delegation scoped to the payment (ERC-20 transfer amount, payee, network), auto-appends redeemer, payee (AllowedCalldataEnforcer), and optional timestamp caveats when existing caveats or parent delegations are not strict enough, signs via signTypedData, and returns delegationManager, encoded permissionContext, and delegator.

Also exports generateSalt from @metamask/smart-accounts-kit/utils (32-byte crypto.getRandomValues), adds @metamask/utils for CAIP eip155 chain parsing (parseEip155ChainId), and documents both in the changelog. Broad unit tests cover the provider and caveat/context helpers.

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

[mj-kiwi]

parseInt can return NaN for non-numeric references (e.g. "eip155:testnet"). consider adding a Number.isFinite check and throwing if invalid.

[jeffsmale90]

good call.

I've changed this to use Number(reference) and added an isNaN check.

[mj-kiwi]

Should we add validation here to enforce expirySeconds > 0? Even though it’s caller-provided config and 0/negative values are unlikely in practice, it might still be safer to guard against them.

[jeffsmale90]

yes!

[mj-kiwi]

I think the payee here is a 20 byte address. ThecreateAllowedCalldataTerms does not ABI-pad the value, so for transfer(address,uint256) we either need to match the 20-byte address at offset 16, or pass a padded address slot at offset 4.

[jeffsmale90]

oof yeah, good catch!

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ 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 ce66c3e. Configure here.}

[mj-kiwi]

LGTM