Add native-token-function-call-stream / -periodic permission types

[banadu3]

Description

Add a new family of Advanced Permission (ERC-7715) types that combine a target/selector restriction with a native-token (or ERC-20) value cap. The currently supported permission types — native-token-stream, native-token-periodic, erc20-token-stream, erc20-token-periodic, erc20-token-revocation — only express value caps and timing, with no way to restrict the call target or function selector.
This schema gap blocks any session-execution pattern that must call a specific contract method instead of transferring raw value (gaming, DeFi strategy bots, auto-rebalance agents, scheduled liquidations, vesting claims, on-chain voting agents, etc.). Without target/selector restrictions, a leaked session key can spend the value cap to an arbitrary recipient, which is unacceptable for any production-grade agent or session-key flow.
The companion option — constructing a custom ERC-7710 delegation with AllowedTargets + AllowedMethods + streaming caveats — is intentionally blocked at the MetaMask Extension signing layer (External signature requests cannot sign delegations for internal accounts.), so the only path forward for general dapps is via Advanced Permissions. That makes filling this schema gap necessary, not optional, for the use cases above.

Proposed new permission types:
// Native token, streaming
{
type: "native-token-function-call-stream",
data: {
target: Address,
selectors: Hex[], // 4-byte function selectors
amountPerSecond: bigint,
initialAmount?: bigint,
maxAmount?: bigint,
startTime?: number,
justification?: string
}
}

// Native token, periodic
{
type: "native-token-function-call-periodic",
data: {
target: Address,
selectors: Hex[],
periodAmount: bigint,
periodDuration: number,
startTime?: number,
justification?: string
}
}
ERC-20 equivalents (erc20-token-function-call-stream, erc20-token-function-call-periodic) for token-paid contract calls in the same shape.

Technical Details

Onchain primitives — already shipped, no new contract work needed.
The Delegation Framework already includes the audited caveat enforcers required to express this permission shape:

• AllowedTargetsEnforcer — restricts the call target.
• AllowedMethodsEnforcer — restricts the function selector(s).
• NativeTokenStreamingEnforcer — linear streaming cap on native value.
• NativeTokenPeriodTransferEnforcer — per-period cap on native value.
• ERC20StreamingEnforcer / ERC20PeriodTransferEnforcer — same for ERC-20.
• TimestampEnforcer — timestamp expiry.
  Each new permission type maps to a fixed combination of these enforcers. No new Solidity is required.
  Where the work sits:

1. ERC-7715 schema definition — add the new type strings and validate data shapes.
2. Permission handler in MetaMask/snap-7715-permissions — translate each new permission type into the corresponding caveat composition: [AllowedTargets, AllowedMethods, NativeTokenStreaming|NativeTokenPeriodTransfer (or ERC-20 variants), Timestamp].
3. Permission picker UI in the Snap — render a human-readable confirmation. Suggested copy: "This dapp can call join(uint8) on 0x1234…ABCD and spend up to 100 POL over 12 hours."

4. Smart Accounts Kit SDK surface — add the permission types to the toolkit's TypeScript types and the docs page at docs.metamask.io/smart-accounts-kit/reference/advanced-permissions/permissions/.
5. signature-controller validateDelegation — no behavior change required. Once the new permission types ship, the resulting delegations will carry a recognized decodedPermission and pass validation through the existing Advanced Permissions path. The current rejection rule in packages/signature-controller/src/utils/validation.ts → validateDelegation() stays as-is.
   Edge cases to handle in the schema validator:

• selectors must be an array of 4-byte hex strings; reject longer or shorter values.
• target must be a valid checksummed address.
• For the streaming variant: if maxAmount is omitted, default behavior should match the existing native-token-stream (no upper cap beyond the streaming rate × time elapsed).
• For the periodic variant: periodDuration must be > 0 and periodAmount > 0.
• selectors array length should be capped (suggest 8) to keep the confirmation UI readable.

Acceptance Criteria

• The five new permission types — native-token-function-call-stream, native-token-function-call-periodic, erc20-token-function-call-stream, erc20-token-function-call-periodic, and (optional) erc20-token-function-call-revocation — are accepted by wallet_grantPermissions.
• Each permission type produces an ERC-7710 delegation with the corresponding caveat composition listed under Technical Details.
• The permission picker UI renders target address, selector(s) (with human-readable function signature where resolvable), amount cap, and time window.
• isAdjustmentAllowed: true lets the user adjust amount, duration, expiry, and start time before approval — but not target or selectors. Target/selector restrictions are part of the security guarantee and must not be loosened by user adjustment.
• Existing native-token-stream / native-token-periodic / ERC-20 permission types continue to behave unchanged.
• Reference docs at docs.metamask.io/smart-accounts-kit/reference/advanced-permissions/permissions/ are updated with parameter tables and code examples in the same shape as existing entries.
• TypeScript types in the Smart Accounts Kit SDK are exported and discoverable through autocomplete.

Scenario 1: granting a contract-scoped streaming permission

• GIVEN a MetaMask user is upgraded to a Smart Account
• WHEN a dapp calls wallet_grantPermissions with type: "native-token-function-call-stream", target: Game, selectors: ["0xcb3e9b84"], a streaming rate, and a maxAmount cap
• THEN the MetaMask permission picker shows a human-readable confirmation including target, function name, streaming rate, and cap
• AND the user can approve, modify amount/duration, or reject
• AND on approval the dapp receives a permission context redeemable through the Delegation Manager
  Scenario 2: redeeming within scope
• GIVEN a session account holds a granted native-token-function-call-stream permission scoped to Game.join(uint8)
• WHEN the session account submits a UserOp that calls Game.join(uint8) with a native value within the streaming cap
• THEN the Delegation Manager validates and the call executes successfully
  Scenario 3: rejecting out-of-scope target
• GIVEN the same granted permission as Scenario 2
• WHEN the session account attempts to call any contract other than Game, OR calls Game with a different selector
• THEN the redeem reverts via AllowedTargetsEnforcer or AllowedMethodsEnforcer
  Scenario 4: rejecting over-cap value
• GIVEN the same granted permission as Scenario 2
• WHEN the session account attempts to call Game.join(uint8) with a native value that exceeds the currently unlocked streaming amount
• THEN the redeem reverts via NativeTokenStreamingEnforcer
  Scenario 5: schema rejection
• GIVEN a dapp calls wallet_grantPermissions with a malformed data payload (e.g. target is not an address, selectors is empty, selectors contains non-4-byte hex, periodDuration ≤ 0)
• THEN the request is rejected with a clear validation error before reaching the permission picker
  Scenario 6: existing permission types unaffected
• GIVEN dapps already integrated against native-token-stream, native-token-periodic, or any ERC-20 permission type
• WHEN those dapps continue to issue the same wallet_grantPermissions payloads after this change ships
• THEN behavior is byte-identical to today (no regressions)

References

• ERC-7715 spec: https://eips.ethereum.org/EIPS/eip-7715
• ERC-7710 spec: https://eips.ethereum.org/EIPS/eip-7710
• Advanced Permissions reference: https://docs.metamask.io/smart-accounts-kit/reference/advanced-permissions/permissions/
• Advanced Permissions concept page: https://docs.metamask.io/smart-accounts-kit/concepts/advanced-permissions/
• Supported Advanced Permissions: https://docs.metamask.io/smart-accounts-kit/get-started/supported-advanced-permissions/
• Snap implementation repo: https://github.com/MetaMask/snap-7715-permissions
• Delegation Framework repo: https://github.com/MetaMask/delegation-framework
• Source of the related signing-layer rejection: MetaMask/core → packages/signature-controller/src/utils/validation.ts → validateDelegation()
• Prior community reports of the related signing-layer blocker:
  https://community.metamask.io/t/advanced-permissions-cannot-express-target-selector-native-value-cap-request-for-a-new-permission-type/31410

[jeffsmale90]

@banadu3 Thanks for raising this issue - and sorry for the delay in responding.

For the first part of your query, we are about to release the payee rule, which allows a requester to specify to which address(es) the allowance may be paid to. Documentation for this should be landing over the next week or so.

For the second part - allowing specific calldata, this is definitely something that we've been thinking about a lot. It's important to us that the caller has a very clear understanding of the authority that they're granting with the permission, so showing 4byte selectors and hex calldata is undesirable.

We have a couple of different options about how to approach this - if you were open to giving us some more context about your specific use case, we would be really happy to take it into account.

[banadu3]

@jeffsmale90 Thanks for the update — and great news about payee. That covers the most important security boundary for our use case: ensuring the session account can only send native POL to the game contract, never to an arbitrary attacker address. We'll integrate against it as soon as the docs land.

On the calldata side, your UX concern makes complete sense — showing 4byte selectors or raw hex to a user would defeat the trust signal that makes Advanced Permissions valuable in the first place. Happy to share the context.

The use case
We're building a prediction market game on Polygon. Each round, a user picks an outcome (binary or multiple-choice) and stakes native POL on their prediction. The on-chain call is PredictionGame.join(uint8 choice) with msg.value as the stake. A typical play session involves 5–10 predictions inside an hour, so a wallet popup per bet makes the game effectively unplayable. The flow we want is: the user grants one permission — "let this game place bets for me, up to 1000 POL over the next 5 hours" — and then plays without interruption.

Why selector restriction still matters once payee is available
With payee alone, our security model is in good shape — POL cannot leave for an attacker address. The remaining concern isn't a drain attack; it's semantic faithfulness and forward-compatibility:

The game contract has other state-changing functions (claim winnings, refund on cancellation, register player). The user only approved playing, not account management.
If we later upgrade the contract and add new payable functions, a session granted today should not retroactively gain authority over them.
For users, "this session can place bets, nothing else" is a much cleaner mental model than "this session can do anything that pays into the game contract."

So payee is a strong floor; selector restriction is what makes the permission feel honest about what it actually authorizes.

Approaches for a human-readable UX
A few directions, roughly from cheapest to most polished:

1. Function signature, not selector. The dapp provides "join(uint8)" and MetaMask computes the 4byte hash internally. Users see the function signature; the dapp can't smuggle in mystery hex. Already a large improvement.

2. Dapp-provided action label. The request includes a short human label per allowed call:

(ts) allowedCalls: [{ signature: "join(uint8)", actionLabel: "Place a bet" }]

MetaMask renders the label as the primary text and exposes the signature as a "details" disclosure for power users. Dapps are incentivized to provide good labels because bad ones cause users to decline.

3. ABI snippet with NatSpec. The dapp provides an ABI fragment, and MetaMask renders @notice as the action description. For us: @notice Place a prediction for the current round would render directly in the confirmation.

4. Verified-contract resolution. For source-verified contracts (Sourcify / Etherscan / Polygonscan), MetaMask resolves NatSpec server-side without the dapp providing anything. Dapp-provided fields become the fallback for unverified contracts.

Our practical preference is (2) as the baseline plus (1) as the underlying mechanism: easy to ship, the label is what users actually read, the signature is the verifiable ground truth underneath, and (3)/(4) layer on later without breaking integrations. Option (1) alone would already unblock us technically; the labeling layer is what makes it feel like a finished consumer flow rather than a developer feature.

We are not asking for arbitrary calldata restriction — we don't need parameter-value matching, regex, or anything like ExactCalldataEnforcer. Just "this session may invoke this named function (or one of these named functions) on the payee contract" would cover the entire class of agent / session-key use cases we care about.

What we can offer
We have a working PoC end-to-end and designed user flows. We're glad to:

• Run a test integration against any early build of payee and provide detailed UX feedback on the calldata confirmation screen.
• Share screenshots / mockups of how the permission picker would ideally read in a consumer game context.
• Try a draft schema in MetaMask/snap-7715-permissions once a direction is chosen.

Looking forward to the payee release, and to whichever direction the team lands on for the calldata side. Happy to chat in any format that's easier than GitHub comments if useful.