--- eip: 8427 title: Portable Spend Grants description: Registered multi-asset spend grants with rolling and lifetime caps author: Chris Madison (@tankcdr) discussions-to: https://ethereum-magicians.org/t/erc-8427-portable-spend-grants/29776 status: Draft type: Standards Track category: ERC created: 2026-09-17 requires: 20, 712, 1271, 7528, 7702 --- ## Abstract A spend grant lets a principal keep its funds in one account and give each delegate a capped, revocable right to spend from it, instead of moving a balance into every delegate's account. The delegate holds a grant identifier, not funds. This specification defines the grant's portable typed terms, which a principal registers on chain and which authorize a delegate to spend one or more assets repeatedly under per-call, trailing-window, and lifetime caps. Native currency of the execution chain is identified by the [ERC-7528](./eip-7528.md) address; every other asset is an [ERC-20](./eip-20.md) contract. An immutable registry stores each grant's terms, usage, and revocation and does not move funds. It identifies a grant by `grantId`, the [EIP-712](./eip-712.md) digest of the registered terms bound to the execution chain and the registry, and the delegate needs only that identifier. By `grantId`, the principal changes a grant's terms in place, keeping its usage, or revokes it, and both parties list their grants and read their state from the registry. A separate executor, fixed by the registry, checks that the delegate authorized each spend and calls `consume` within the same call as the value movement, so that neither happens without the other. Caps never treat zero as unlimited. The terms are portable: any wallet or tool can hash, render, and check them identically. A grant is bound to one chain and one registry, and through the registry to one executor; using a different one requires a new registration. ## Motivation A principal that lets delegates, such as software agents, spend for it commonly moves a balance into an account for each delegate and enforces limits off chain. Each such account holds funds the principal cannot use elsewhere, needs topping up and sweeping, and must be emptied to end the delegate's access, and its limits can be read only through the service that enforces them. A principal should be able to keep its funds in its own account and give each delegate a bounded, revocable right to spend from it, with the bounds on chain. Approvals and one-shot signatures do not give wallets, applications, and relying parties a shared object for bounded spend. An [ERC-20](./eip-20.md) allowance is usually a single-asset, uncapped, non-expiring debit right. Recurring allowances that reset at a UTC day or calendar period allow two full spends on either side of midnight. Multi-asset grants need each asset to carry its own remaining, so that one grant can cover several assets without one asset's spending drawing down another's. Delegation and permission RPCs exist, but they leave the meaning of the permission opaque. Two implementations can show the same hash and still disagree on window arithmetic, native-currency encoding, or whether a second asset has its own remaining. Principals also need to revoke or tighten a grant without the delegate's cooperation, with a tighter cap counting what was already spent, and both parties need to find the grants between them, and what remains under each, from the chain rather than from records each keeps. Existing tokens and native currency should not have to opt into a hook in order to be spent under a grant. The grant should be portable typed terms with a canonical rendering and a JSON interchange, held by an on-chain registry that the principal updates and revokes by identifier and that any conformant executor debits atomically with movement. ## Specification The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174. Bytes are hashed with Ethereum Keccak-256. The digest of a grant's terms is the complete [EIP-712](./eip-712.md) digest defined in [Domain and digest](#domain-and-digest). Amounts are raw asset units: for native currency, the unit of `msg.value` and `BALANCE` on the execution chain (wei on Ethereum); for [ERC-20](./eip-20.md), the token's `decimals` units. This specification does not define compilation into other permission systems. ### Terms - **Principal:** the address that registers the grant and whose assets are spent. - **Delegate:** the address named in the terms as the grantee. Only the delegate may authorize a spend under the grant. The executor authenticates who authorized each spend and passes that address to `consume`, which rejects any address other than `delegate` (see [Executor](#executor)). - **Executor:** the immutable address returned by the registry `executor()` function. Only this address may call `consume`. - **Recipient:** the payee of a single `consume`; never zero, the principal, the registry, the executor, or the asset being spent. - **Registry:** the immutable contract that stores grants, usage, and revocations. It NEVER transfers assets. - **grantId:** the identifier the registry assigns a grant at registration, equal to the digest of the registered terms (see [Domain and digest](#domain-and-digest)). It never changes, so after an `update` it can differ from the digest of the grant's current terms. - **Window:** a trailing `lookback` of `windowSeconds` seconds, not a UTC calendar day. - **NATIVE:** the [ERC-7528](./eip-7528.md) address `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`, which denotes the execution chain's native currency. ### Grant object The exact types, field order, and integer widths are: ```solidity struct AssetLimit { address asset; // ERC-20, or NATIVE (ERC-7528) for this chain's native currency uint256 maxPerCall; // one payment, raw units uint256 maxPerWindow; // trailing window, raw units uint256 maxTotal; // lifetime, never resets } struct SpendGrant { address principal; address delegate; uint8 recipientMode; // 0 = one address, 1 = any address recipient; // required nonzero if mode is 0; MUST be address(0) if mode is 1 uint8 assetCombine; // MUST be 0 (independent per-asset caps); other values reserved uint64 windowSeconds; // trailing lookback; 86400 = 24 hours, not a UTC day AssetLimit[] assets; // 1–16, unique, strictly ascending by uint160(asset) uint64 validAfter; // inclusive unix seconds uint64 validUntil; // exclusive unix seconds uint256 salt; } ``` All fields are required. `salt` distinguishes otherwise identical terms, so that a principal can register a grant whose other fields equal an earlier grant's, revoked or not; it is not an execution nonce. Grants never supersede one another: every unrevoked grant stays spendable within its own caps, so a second grant to the same delegate, even for the same asset, adds its caps to the first. A principal changes a grant's terms with `update` (see [Registering and changing a grant](#registering-and-changing-a-grant)). ### Encode type The exact `encodeType` for `SpendGrant` is the following single string, including the concatenated `AssetLimit` definition and with no spaces: ``` SpendGrant(address principal,address delegate,uint8 recipientMode,address recipient,uint8 assetCombine,uint64 windowSeconds,AssetLimit[] assets,uint64 validAfter,uint64 validUntil,uint256 salt)AssetLimit(address asset,uint256 maxPerCall,uint256 maxPerWindow,uint256 maxTotal) ``` The `AssetLimit` `encodeType` is: ``` AssetLimit(address asset,uint256 maxPerCall,uint256 maxPerWindow,uint256 maxTotal) ``` `SPENDGRANT_TYPEHASH` is `keccak256` of the SpendGrant `encodeType` bytes. `ASSETLIMIT_TYPEHASH` is `keccak256` of the `AssetLimit` `encodeType` bytes. ### Domain and digest The domain uses exactly four fields: `name = "SpendGrant"`, `version = "1"`, `chainId` equal to the execution chain ID, and `verifyingContract` equal to the registry address. The domain MUST NOT include `salt` or additional fields. The registry MUST be deployed on the execution chain. A change of chain, registry, or executor requires a new registration. ``` EIP712Domain(string name,string version,uint256 chainId,address verifyingContract) ``` ``` domainSeparator = keccak256( abi.encode( keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"), keccak256("SpendGrant"), keccak256("1"), chainId, registry ) ) ``` String values are hashed as UTF-8 bytes. `abi.encode` above is the 32-byte ABI word encoding of each field. Each `AssetLimit` element is hashed as: ``` hashStruct(AssetLimit) = keccak256( abi.encode( ASSETLIMIT_TYPEHASH, asset, maxPerCall, maxPerWindow, maxTotal ) ) ``` The `assets` array hash is `keccak256` of the concatenation of those 32-byte element hashes in `assets` order. There MUST NOT be an ABI offset, a length prefix, or any other padding between element hashes. That 32-byte array hash occupies the `assets` word in the primary struct hash. ``` hashStruct(SpendGrant) = keccak256( abi.encode( SPENDGRANT_TYPEHASH, principal, delegate, recipientMode, recipient, assetCombine, windowSeconds, assetsArrayHash, validAfter, validUntil, salt ) ) ``` Atomic types are encoded as 32-byte ABI words (uint8 and uint64 are zero-extended). The digest of a grant's terms is: ``` digest = keccak256(0x1901 || domainSeparator || hashStruct(SpendGrant)) ``` `0x1901` is a two-byte prefix. Implementations MUST NOT substitute `hashStruct(SpendGrant)` or the domain separator for the digest. A grant's `grantId` is the digest of the terms passed to `register`, and it does not change when the terms do (see [Registry](#registry)). The digest is not signed: a principal registers terms by calling `register`. ### Structural validation A grant is structurally valid only if every condition below holds. `register` and `update` apply these conditions to the terms they are given (see [Registering and changing a grant](#registering-and-changing-a-grant)). Unknown future values of `recipientMode` and `assetCombine` MUST fail closed. Zero MUST NOT be interpreted as unlimited. - `principal` and `delegate` are nonzero, and `delegate != principal`. - `recipientMode` is `0` or `1`. - If `recipientMode == 0`, `recipient` is nonzero and `recipient != principal`. - If `recipientMode == 1`, `recipient == address(0)`. - `assetCombine == 0`. Every other value is reserved for a future version of this specification and MUST be rejected. - `windowSeconds > 0`. - `validAfter < validUntil`. - `assets.length` is in `1 ..= 16`. - `assets` are strictly ascending by `uint160(asset)` and contain no duplicate addresses. - For every asset: `maxPerCall > 0`, `maxPerWindow > 0`, `maxTotal > 0`, and `maxPerCall <= maxPerWindow <= maxTotal`. - No asset is `address(0)`. - `NATIVE` MUST NOT be rewritten to a wrapped-token address and MUST NOT be required to have code. Whether a listed asset has code is checked at `consume`, for the asset being spent only (see [Registry](#registry)). `register` and `update` also apply a registration rule: when `recipientMode == 0`, `recipient` MUST NOT be the registry, `executor()`, or any listed asset. `consume` rejects the registry and the executor as payees in either mode, and the asset being spent (see [Registry](#registry)), so such a grant could never pay in at least one asset it lists, and the registry refuses it rather than store a grant that `grantState` would show as spendable in an asset no spend could pay. ### Caps A single `consume` spends exactly one asset. `amount` MUST be greater than zero and MUST be less than or equal to that asset's `maxPerCall`. Each listed asset has independent remaining window and lifetime, recorded per `(grantId, asset)`. Spending one asset MUST NOT reduce another asset's remaining. The caps in force are those of the grant's current terms, evaluated against all usage recorded for the grant since registration, including usage recorded under earlier terms. For the selected asset, let `windowSpent` be the sum of unexpired debit `amount`s and `lifetimeSpent` be the sum of all debit `amount`s. `consume` MUST revert if `windowSpent + amount > maxPerWindow` or `lifetimeSpent + amount > maxTotal`. Equality is permitted and exhausts that cap. Implementations MUST evaluate these comparisons without overflow. ### Rolling window A debit recorded at timestamp `s` (the `block.timestamp` of the successful `consume`) counts in the window if and only if `block.timestamp < s + windowSeconds` in 256-bit arithmetic, with `windowSeconds` zero-extended. Equivalently, the debit counts while `block.timestamp - s < windowSeconds` when `block.timestamp >= s`, and it expires at age `== windowSeconds`. Midnight and UTC day boundaries have no effect. Lifetime remaining never resets. Exact rolling requires timestamped debits. Views MUST recompute unexpired totals at the queried block and MUST NOT return a stale stored window counter. An implementation MAY bound the number of live (unexpired) stored debits per `(grantId, asset)`. The reference bound is 1024. If a bound is in force and a further debit would exceed it, `consume` MUST revert. That bound is an implementation limit, not a cap in the terms. Expired debits MAY be dropped from storage; they MUST remain excluded from window checks and rolling views. `evict(grantId, asset, maxCount)` drops up to `maxCount` expired debits from storage for that asset and nothing else: anyone MAY call it, it MUST NOT change what any check or view returns, and an implementation that keeps no expired debits MAY make it a no-op. It lets a wallet or relayer pay for dropping a burst of expired debits in bounded pieces instead of leaving the whole cost on the next `consume`. This specification assumes `block.timestamp` does not decrease from one block to the next. An implementation MAY also bound the stored width of a single debit `amount`. The reference stores amounts in 192 bits. If such a bound is in force, a `consume` whose `amount` exceeds it MUST revert with `OVER_TX_CAP`. ### Registering and changing a grant A grant exists once its principal registers it, and only the principal can update or revoke it. Each function below MUST check its conditions in the order listed and revert with the error of the first that fails; the errors are declared in [Registry](#registry). `register(terms)` MUST revert with: 1. `NotPrincipal()` unless `msg.sender == terms.principal`. 1. `SpendGrantError(INVALID_GRANT)` unless `terms` are structurally valid and meet the registration rule (see [Structural validation](#structural-validation)). 1. `GrantExists(grantId)` if `grantId`, the digest of `terms` on this registry, is already registered. Otherwise it stores the terms, sets the grant's `version` to `1` and its `createdAt` and `updatedAt` to `block.timestamp`, appends `grantId` to the principal's list and to the delegate's list, emits `GrantRegistered(grantId, principal, delegate, terms)`, and returns `grantId`. A grant is registered if and only if its stored `principal` is nonzero. A revoked grant stays registered, so registering the same terms again reverts with `GrantExists`; another grant with otherwise identical terms needs a different `salt`. `update(grantId, expectedVersion, terms)` replaces a grant's terms in place. It MUST revert with: 1. `UnknownGrant(grantId)` if `grantId` is not registered. 1. `NotPrincipal()` unless `msg.sender` is the grant's principal. 1. `GrantIsRevoked(grantId)` if the grant is revoked. 1. `StaleVersion(current)` unless `expectedVersion` equals the grant's `version`, reported as `current`, so that an update built against an earlier version, for example one delayed behind another, cannot silently undo a newer change. 1. `FixedField()` unless `terms.principal`, `terms.delegate`, and `terms.windowSeconds` equal the grant's. 1. `SpendGrantError(INVALID_GRANT)` unless `terms` are structurally valid and meet the registration rule. `terms.salt` is ignored: the grant keeps the `salt` it was registered with, and its `grantId`. Otherwise `update` replaces `recipientMode`, `recipient`, `validAfter`, `validUntil`, and `assets`, keeping no entry of the earlier `assets` that `terms.assets` omits; increments `version` by one; sets `updatedAt` to `block.timestamp`; leaves the grant's usage unchanged; and emits `GrantUpdated(grantId, principal, delegate, version, terms)` with the new `version` and with the registration `salt` in place of `terms.salt`, so that the event carries the terms `getGrant` returns. `revoke(grantId)` MUST revert with `UnknownGrant(grantId)` if `grantId` is not registered, and then with `NotPrincipal()` unless `msg.sender` is the grant's principal. Otherwise, if the grant is not yet revoked, it marks the grant revoked and emits `GrantRevoked(grantId, principal, delegate)`; revoking a revoked grant returns without an event. There is no `unrevoke`. The registry keeps no earlier version of a grant's terms; `GrantRegistered` and `GrantUpdated` carry the full terms of every version. `grantsOf` and `grantsTo` list every grant registered with a principal or a delegate, in registration order. Entries are never removed, so revoked grants stay listed and a reader filters them by the `isRevoked` that `getGrant` returns. An update applies to every later `consume`, and the caps in force are always the current terms', evaluated against all usage since registration (see [Caps](#caps)). In particular: - Lowering `maxTotal` to or below the asset's lifetime `spent` exhausts that asset. - Lowering `maxPerWindow` to or below the asset's unexpired window spend blocks it until enough debits expire. - Removing an asset makes spends of it fail with `WRONG_ASSET` but keeps its usage; listing it again resumes from that usage. - Setting `validUntil` after the current time revives an expired grant, and setting it at or before the current time ends the grant (`EXPIRED`). - Setting `validAfter` after the current time pauses the grant (`NOT_YET_VALID`), and setting it back resumes it. - A new `recipientMode` or `recipient` applies from the next `consume`. A different delegate, for example after a key rotation, or a different window needs a revocation and a new registration, and the new grant starts with no usage, so its caps add to what was spent under the earlier grant unless the principal sizes them against that grant's `usage`. ### Signatures These rules validate a signature by a signer over a digest. This specification applies them to delegate-signed authorizations (see [Executor](#executor)), with the delegate as the signer and the authorization's digest. If the signer has no code at the evaluated block, the signature MUST be exactly 65 bytes `r || s || v` of secp256k1 over the digest, with `v` equal to `27` or `28`, `s` in the lower half of the curve order (`s <= 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0`), and recovered address equal to the signer. If the signer has code at the evaluated block and that code is not an [EIP-7702](./eip-7702.md) delegation designator, the signature MUST be validated with [ERC-1271](./eip-1271.md) `isValidSignature(digest, signature)` against execution-time state. The call MUST be made with `STATICCALL`: `isValidSignature` is declared `view`, and a static call rules out any state change, and so any reentrant spend, during validation. The call MUST return exactly 32 bytes equal to the 32-byte word `0x1626ba7e` left-aligned (28 trailing zero bytes). A raw four-byte return, a revert, a malformed return, or any other value is invalid. Implementations MUST NOT fall back to ECDSA recovery for a code-bearing signer. If the signer's code at the evaluated block is exactly 23 bytes beginning with `0xef0100` (an [EIP-7702](./eip-7702.md) delegation designator), the signature is valid if either (a) it satisfies the 65-byte secp256k1 rule above and recovers the signer, or (b) the [ERC-1271](./eip-1271.md) call above succeeds against the delegated code. Implementations MUST try (a) first and MUST NOT require (b) when (a) holds. A cached ERC-1271 success MUST NOT replace execution-time validation. ### Canonical rendering The canonical rendering is a plain-text form of a grant, derived entirely from the grant's fields and the domain, and carries no information the typed data does not. A plain-text presentation of a grant's complete terms in raw values, such as a record, log, or export that stands for the grant, MUST use exactly these bytes, so that two implementations show the same text for the same grant. A display that converts values (raw units to token units, timestamps to dates, addresses to names), summarizes, or shows only some of the terms is a formatted display, whatever its medium (graphical, a clear-signing descriptor, or terminal text), and is not constrained by this section. The rendering is ASCII (hence UTF-8), uses LF (`0x0a`) line endings, and contains exactly one trailing LF. It MUST NOT use `CR`, `CRLF`, a `BOM`, trailing spaces, or blank lines. Addresses are `0x` followed by 40 lowercase hexadecimal digits (no mixed-case checksum). Unsigned integers are canonical decimal: `0`, or a digit `1`–`9` followed by zero or more digits, with no sign, fraction, exponent, or leading zeros. `i` in budget lines is the 0-based index in `assets` order. Budget lines are repeated for each asset in that order. Labels and spacing are exact: ``` Spend grant v1 Chain: {chainId} Registry: {registry} Principal: {principal} Delegate: {delegate} Recipient mode: {recipientMode} Recipient: {recipient} Asset combine: {assetCombine} Window seconds: {windowSeconds} Budget count: {n} Budget {i} asset: {asset} Budget {i} maximum per call (raw units): {maxPerCall} Budget {i} maximum per window (raw units): {maxPerWindow} Budget {i} maximum total (raw units): {maxTotal} Valid after (inclusive Unix seconds): {validAfter} Valid until (exclusive Unix seconds): {validUntil} Salt: {salt} ``` The canonical rendering does not include the executor address. A wallet SHOULD also display `executor()` of `{registry}` before the principal registers or updates a grant, because only that address can call `consume`, and it authenticates the delegate and moves the principal's funds. ### JSON interchange The interchange object carries a grant's terms between applications, whether proposed for registration or read from a registry. It contains exactly `chainId`, `registry`, and `grant`. `grant` contains exactly the SpendGrant fields: `principal`, `delegate`, `recipientMode`, `recipient`, `assetCombine`, `windowSeconds`, `assets`, `validAfter`, `validUntil`, `salt`. Each element of `assets` contains exactly `asset`, `maxPerCall`, `maxPerWindow`, `maxTotal`. When hashing a grant from interchange JSON, implementations MUST use `chainId` as the domain `chainId` and `registry` as `verifyingContract`. Unsigned integers MUST be JSON strings in canonical decimal form as defined for rendering, and MUST fit the field width (`uint8`, `uint64`, or `uint256`). Addresses MUST be lowercase `0x` plus 40 hex digits. Hex MUST use `[0-9a-f]` only. Implementations MUST reject extra fields, missing fields, duplicate JSON member names (rejected before object conversion), JSON numbers in place of integer strings, uppercase hex, leading zeros other than the value `0`, out-of-range values, wrong types, `null`, and trailing commas. Object property order and insignificant white space do not affect the digest. Implementations MUST NOT use a JSON byte hash in place of the digest. Illustrative shape (values are examples, not vectors): ```json { "chainId": "1", "registry": "0x1111111111111111111111111111111111111111", "grant": { "principal": "0x2222222222222222222222222222222222222222", "delegate": "0x3333333333333333333333333333333333333333", "recipientMode": "0", "recipient": "0x4444444444444444444444444444444444444444", "assetCombine": "0", "windowSeconds": "86400", "assets": [ { "asset": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "maxPerCall": "1000000000000000000", "maxPerWindow": "5000000000000000000", "maxTotal": "10000000000000000000" } ], "validAfter": "0", "validUntil": "1893456000", "salt": "1" } } ``` ### Registry The registry is immutable: no admin, no pause, no upgrade, no `unrevoke`, and no proxy. The executor address is set in the constructor to a nonzero value and NEVER changes. A principal binds that executor by registering grants with this registry. ```solidity enum Reason { OK, INVALID_GRANT, BAD_SIGNATURE, NOT_YET_VALID, EXPIRED, REVOKED, WRONG_ASSET, WRONG_RECIPIENT, OVER_TX_CAP, OVER_WINDOW_CAP, OVER_CUMULATIVE_CAP, WINDOW_FULL, UNAUTHORIZED_EXECUTOR, UNAUTHORIZED_DELEGATE, NONEXISTENT } error SpendGrantError(Reason reason); // ABI signature SpendGrantError(uint8) error NotPrincipal(); error GrantExists(bytes32 grantId); error UnknownGrant(bytes32 grantId); error GrantIsRevoked(bytes32 grantId); error StaleVersion(uint256 current); error FixedField(); error InsufficientGas(); struct GrantState { Reason status; uint256 maxPerCall; uint256 maxPerWindow; uint256 maxTotal; uint256 spent; // lifetime uint256 windowSpent; // unexpired uint256 liveDebits; // unexpired debit count uint256 nextExpiry; // expiresAt of the oldest unexpired debit; 0 if none uint256 balance; // principal's balance of the asset uint256 allowance; // principal's ERC-20 allowance to the executor bool balanceKnown; bool allowanceKnown; uint256 spendableNow; } interface ISpendGrantRegistry { event GrantRegistered( bytes32 indexed grantId, address indexed principal, address indexed delegate, SpendGrant terms ); event GrantUpdated( bytes32 indexed grantId, address indexed principal, address indexed delegate, uint256 version, SpendGrant terms ); event GrantRevoked(bytes32 indexed grantId, address indexed principal, address indexed delegate); event GrantConsumed( bytes32 indexed grantId, address indexed principal, address asset, uint256 amount, address indexed recipient ); function executor() external view returns (address); function hashGrant(SpendGrant calldata terms) external view returns (bytes32); function register(SpendGrant calldata terms) external returns (bytes32 grantId); function update(bytes32 grantId, uint256 expectedVersion, SpendGrant calldata terms) external; function revoke(bytes32 grantId) external; function revoked(bytes32 grantId) external view returns (bool); function getGrant(bytes32 grantId) external view returns (SpendGrant memory terms, uint256 version, uint256 createdAt, uint256 updatedAt, bool isRevoked); function parties(bytes32 grantId) external view returns (address principal, address delegate); function grantsOf(address principal, uint256 offset, uint256 limit) external view returns (bytes32[] memory grantIds, uint256 total); function grantsTo(address delegate, uint256 offset, uint256 limit) external view returns (bytes32[] memory grantIds, uint256 total); function usage(bytes32 grantId, address asset) external view returns (uint256 spent, uint256 calls); function rollingUsage(bytes32 grantId, address asset) external view returns (uint256 spent, uint256 calls); function liveDebits(bytes32 grantId, address asset, uint256 maxCount) external view returns (uint256[] memory expiresAt, uint256[] memory amounts); function evict(bytes32 grantId, address asset, uint256 maxCount) external; function grantState(bytes32 grantId, address asset) external view returns (GrantState memory); function check(bytes32 grantId, address authorizer, address asset, uint256 amount, address recipient) external view returns (bool ok, Reason reason); function consume(bytes32 grantId, address authorizer, address asset, uint256 amount, address recipient) external; } ``` `register`, `update`, and `revoke` behave as specified in [Registering and changing a grant](#registering-and-changing-a-grant). Revert data is normative: a revert for a reason in [Reason names](#reason-names) MUST carry the ABI encoding of `SpendGrantError(uint8)`, whose selector is `bytes4(keccak256("SpendGrantError(uint8)"))`, with the reason's number as its argument, and a revert with any other error this specification names MUST carry that error's ABI encoding. `executor()` returns the immutable executor. `authorizer` is the address the executor authenticated as authorizing this spend (see [Executor](#executor)). `consume` MUST validate, then record the debit, then emit `GrantConsumed`, then return. It MUST NOT move tokens, send native currency, or call the selected asset for transfer. `consume` MUST revert with `SpendGrantError(UNAUTHORIZED_EXECUTOR)` unless `msg.sender == executor()`. It then evaluates the spend against the grant's current terms and MUST revert with `SpendGrantError(reason)` for the first of the following conditions that fails, using the reason names in [Reason names](#reason-names): 1. `grantId` is registered (`NONEXISTENT`). 1. `authorizer` equals the grant's `delegate` (`UNAUTHORIZED_DELEGATE`). 1. `block.timestamp >= validAfter` (`NOT_YET_VALID`). 1. `block.timestamp < validUntil` (`EXPIRED`). 1. The grant is not revoked (`REVOKED`). 1. The `recipient` argument is nonzero and is not the grant's `principal`, the registry, `executor()`, or `asset`, in either mode; and if `recipientMode == 0`, the argument equals the grant's `recipient` (`WRONG_RECIPIENT`). 1. `asset` equals `assets[j].asset` for exactly one `j` (`WRONG_ASSET`). 1. If `asset` is not `NATIVE`, it has code at the evaluated block (`EXTCODESIZE > 0`), and that code is not an [EIP-7702](./eip-7702.md) delegation designator, which marks an account rather than a token (`INVALID_GRANT`). A listed asset that is not being spent is not checked, so a listing without code does not block the grant's other assets. 1. `amount > 0`, `amount <= assets[j].maxPerCall`, and `amount` is within any implementation amount bound (`OVER_TX_CAP`). 1. The spend does not exceed the window cap as defined in [Caps](#caps) (`OVER_WINDOW_CAP`). 1. The spend does not exceed the lifetime cap (`OVER_CUMULATIVE_CAP`). 1. Recording the debit does not exceed the live-debit bound, if any (`WINDOW_FULL`). `check(grantId, authorizer, asset, amount, recipient)` evaluates the same conditions in the same order for any caller, without the executor condition, and returns `(true, OK)` if all hold, or `false` and the reason of the first that fails. For every state and input, given enough gas for `consume` to complete, `check` MUST return `OK` if and only if `consume`, called by the executor with the same arguments in the same state and block, succeeds; when it does not, `consume` MUST revert with exactly `SpendGrantError(reason)` for the reason `check` returns. A registry MUST NOT give `consume` any failure mode outside [Reason names](#reason-names), such as a per-transaction lock that `check` cannot see. On success the registry appends a timestamped debit for `(grantId, asset)` with the consumed `amount` and emits `GrantConsumed(grantId, principal, asset, amount, recipient)`. `calls` counts successful `consume` executions for that `(grantId, asset)` and is observation only; it is not a cap. `GrantConsumed` indexes `grantId`, the grant's `principal`, and `recipient`: the lists give each party's grants and the events their history, a principal's wallet can find every spend against it by filtering on its own address, and a payee can watch for payments to itself; `asset` and `amount` are data. `amount` is what the executor requested from the asset, not what the payee received: a token that deducts a fee delivers less, and a payee that needs the delivered amount reads the asset's own `Transfer` event or its balance change. View behavior: - `hashGrant(terms)` returns the digest of `terms` on this registry and chain, which is the `grantId` that `register(terms)` would assign. It performs no validation and changes no state. After an `update` the digest of a grant's current terms can differ from its `grantId`, so implementations MUST NOT derive a registered grant's identifier from its current terms; a recorded grant is referenced as `(chainId, registry, grantId)`. - `revoked(grantId)` is true if the grant is registered and revoked, and false otherwise. - `getGrant(grantId)` returns the grant's stored terms, with `assetCombine` `0` and the `salt` given at registration, and its `version`, `createdAt`, `updatedAt`, and `isRevoked`. For an identifier that is not registered it returns zero values, including a zero `principal`, and does not revert. - `parties(grantId)` returns the grant's `principal` and `delegate`, or zero addresses for an identifier that is not registered. - `grantsOf(principal, offset, limit)` and `grantsTo(delegate, offset, limit)` return `total`, the length of that address's list, and the identifiers from position `offset` up to but excluding position `min(offset + limit, total)`, computed without overflow for any `limit`. The array is empty when `offset >= total` or `limit == 0`. - `usage` returns lifetime raw `spent` (sum of `amount` over every successful consume of that asset, including those that have left the window) and lifetime `calls`. - `rollingUsage` returns the same pair recomputed over unexpired debits only. - `liveDebits(grantId, asset, maxCount)` returns the oldest `min(maxCount, n)` of the `n` unexpired debits for that asset at the queried block, in the order they were recorded. `expiresAt[i]` is that debit's recorded timestamp plus `windowSeconds` in 256-bit arithmetic, `amounts[i]` is its `amount`, and the two arrays have equal length; the debit counts against the window while `block.timestamp < expiresAt[i]`. When `maxCount >= n`, `amounts` sums to `rollingUsage`'s `spent` and `n` equals its `calls` at the same block. Like `rollingUsage`, it MUST be recomputed at the queried block. - `usage`, `rollingUsage`, and `liveDebits` take the window length from the grant's stored terms and return zeros for an identifier that is not registered, for which `evict` does nothing. `grantState(grantId, asset)` reports one asset of a grant at the queried block: - `status` is the reason of the first failing condition among conditions 1, 3, 4, 5, 7, and 8 of the `consume` order (`NONEXISTENT`, `NOT_YET_VALID`, `EXPIRED`, `REVOKED`, `WRONG_ASSET`, `INVALID_GRANT`), or `OK` if none fails. - `maxPerCall`, `maxPerWindow`, and `maxTotal` are the asset's caps in the current terms, or `0` when the grant is not registered or the asset is not listed in its current terms. - `spent` and `windowSpent` are the `spent` values of `usage` and `rollingUsage`, `liveDebits` is the `calls` value of `rollingUsage`, and `nextExpiry` is the `expiresAt` of the oldest unexpired debit, or `0` if there is none. They are reported even for an asset the current terms no longer list. - `balance` is the principal's balance of the asset and `allowance` its ERC-20 allowance to `executor()`. They are read only when the grant is registered, the asset is listed, and the asset meets condition 8; otherwise each is `0` and its flag, `balanceKnown` or `allowanceKnown`, is false. For `NATIVE`, the read gives the principal's native balance as `balance` and `type(uint256).max` as `allowance`, meaning no ERC-20 allowance applies, with both flags true. For an ERC-20, each read MUST be a `STATICCALL` that forwards exactly 100,000 gas and copies at most one word of return data, and the value is known, with its flag true, only if the call succeeds and returns exactly 32 bytes; otherwise the value is `0` and its flag false. Before each read the view MUST revert with `InsufficientGas()` unless enough gas remains to forward the whole stipend under the 63/64 rule, so that an unknown value means the asset failed the read, never that the caller supplied too little gas. Apart from that, `grantState` MUST NOT revert because of anything the asset does. - `spendableNow` is `0` unless `status` is `OK`. Otherwise it is the least of `maxPerWindow - windowSpent` and `maxTotal - spent`, each `0` if negative; where the registry bounds live debits, the free slots (the bound minus `liveDebits`) times the lesser of `maxPerCall` and any implementation amount bound, saturating at `type(uint256).max`; `balance`; and `allowance`, with an unknown value counted as `0`. The live-debit and amount bounds are implementation parameters, 1024 and `type(uint192).max` in the reference. A single payment is further limited to the lesser of `maxPerCall` and any implementation amount bound. `check` and `grantState` describe the registry's state, not whether its executor can move the asset: an executor that cannot move `NATIVE`, as the reference executors cannot, fails a `NATIVE` spend that `check` reports as `OK`. A wallet that displays a grant, before or after registration, SHOULD describe the window as a trailing window of `windowSeconds` seconds, not a calendar period; a plain-text display says so outside the canonical rendering rather than changing it. After registration, a wallet SHOULD also show, for each asset, how much can be spent now and when more becomes available, reading `grantState` and `liveDebits` at the same block. The principal's balance and, for an ERC-20, its allowance to the executor are shared with every other grant that draws on them. Window spend frees up as each debit returned by `liveDebits` reaches its `expiresAt`, but only up to what `maxTotal` still allows and only before `validUntil`; lifetime spend never frees up. A wallet SHOULD show the total of all unrevoked grants to a delegate rather than the newest alone, because grants stack (see [Grant object](#grant-object)). ### Reason names These names and numbers are the normative vocabulary. A reason's number is its value in `Reason` and the argument of `SpendGrantError(uint8)`. A number never changes meaning: a later version only appends names, and numbers do not imply evaluation order. `consume` returns nothing on success; on failure it MUST revert with exactly one reason other than `OK`. `check` returns the same reasons, with `OK` for a spend that would succeed. `BAD_SIGNATURE` is reserved: this version defines no grant signature, and no function returns it. | Number | Name | Condition | | --- | --- | --- | | 0 | `OK` | Success | | 1 | `INVALID_GRANT` | Terms passed to `register` or `update` fail structural validation or the registration rule, or the asset being spent is not `NATIVE` and has no code or is an EIP-7702 delegated account | | 2 | `BAD_SIGNATURE` | Reserved; never returned | | 3 | `NOT_YET_VALID` | `block.timestamp < validAfter` | | 4 | `EXPIRED` | `block.timestamp >= validUntil` | | 5 | `REVOKED` | The principal has revoked the grant | | 6 | `WRONG_ASSET` | `asset` is not in the grant's current `assets` | | 7 | `WRONG_RECIPIENT` | `recipient` is zero, the principal, the registry, the executor, or the asset being spent, or `recipientMode == 0` and it is not the grant's `recipient` | | 8 | `OVER_TX_CAP` | `amount == 0`, `amount > maxPerCall`, or `amount` exceeds an implementation amount bound | | 9 | `OVER_WINDOW_CAP` | Trailing-window cap would be exceeded | | 10 | `OVER_CUMULATIVE_CAP` | Lifetime cap would be exceeded | | 11 | `WINDOW_FULL` | Live unexpired debit bound would be exceeded | | 12 | `UNAUTHORIZED_EXECUTOR` | The caller of `consume` is not the immutable executor | | 13 | `UNAUTHORIZED_DELEGATE` | `authorizer` is not the grant's `delegate` | | 14 | `NONEXISTENT` | `grantId` is not registered | ### Executor A conformant executor MUST call `consume` and perform the movement of `amount` of `asset` from the grant's principal to `recipient` within one call to the executor, and that call MUST revert if `consume` fails or the movement fails, so that neither happens without the other. The movement MUST come from the principal's own balance; the executor MUST NOT fund it from its caller, its own balance, or any other account. Order of `consume` and movement is unspecified. A conformant executor MUST call `consume` only on a registry that it fixes at deployment or otherwise trusts by address, and MUST NOT take the registry from its caller or any other call input; checking that a registry's `executor()` returns the executor's own address is not enough, because anyone can deploy a contract that does so and accepts every call. A conformant executor MUST read a grant's principal and delegate from that registry, for example with `parties(grantId)`, and never take them from call input. When `parties` returns a zero principal, the `grantId` is not registered, and the executor SHOULD revert with `SpendGrantError(NONEXISTENT)`, the reason `consume` would give. A conformant executor MUST NOT initiate any movement of any asset out of the principal, in any function, other than the one movement paired with a successful `consume`, and MUST NOT take a fee or other charge from the principal; such a charge would fall outside every cap the principal set. The `amount` passed to `consume` MUST equal the amount the executor requests in that movement. The caps bound what the executor asks the asset to move, which for an ERC-20 is also what the principal's allowance to the executor bounds; what the asset's own code does with that request, such as charging a transfer fee or rounding a share-based balance, is the asset's behavior, not the executor's, and does not affect the executor's conformance (see [Security Considerations](#security-considerations)). Before calling `consume`, a conformant executor MUST authenticate who authorized this spend of `amount` of `asset` to `recipient`, and MUST pass the address that authentication produced as `authorizer`. Knowing a `grantId` is not authorization: identifiers are public. Whatever the mechanism, each successful `consume` MUST correspond to one authorization by the delegate that names that `grantId`, `asset`, `amount`, and `recipient`, and an authorization MUST NOT produce more than one successful `consume`. Mechanisms include: - **Direct call.** The delegate calls the executor. `authorizer` is `msg.sender`. - **Signed authorization.** The delegate signs this spend and anyone may submit it. The signed message MUST include `grantId`, `asset`, `amount`, `recipient`, and a nonce. It SHOULD include a deadline and MUST be [EIP-712](./eip-712.md) typed data whose `verifyingContract` is the executor, so that its digest is defined. The executor MUST validate the signature by the rules in [Signatures](#signatures) over the digest of that message, taking the grant's delegate as the signer, except that for a delegate without code it MAY pass the address recovered under those rules as `authorizer` and leave the comparison with the delegate to `consume`; it MUST reject it at or after any deadline, and MUST record the nonce, not the signature bytes, in a namespace scoped to the authorizer or to `grantId`, so that the authorization succeeds at most once. It MUST record the nonce before calling `consume` or moving funds, because the movement can call out, for example through token hooks, and reenter the executor. It SHOULD check the nonce before validating the signature, so that a submitter who lost the race pays for a storage read rather than for the delegate's ERC-1271 call. It SHOULD let the delegate invalidate an unused nonce, and that invalidation MUST fail for a nonce that already succeeded or was already invalidated, so that a successful invalidation proves the authorization never ran and never will. `authorizer` is the signer the executor recovered, or, for a delegate with code, the address whose ERC-1271 validation succeeded. - **Delegation framework.** Where the delegate redeems through a delegation manager contract, the manager validates the delegation and the delegator's account performs the execution. The executor is therefore called by that account, not by the manager and not by the redeemer. Two shapes follow. - If the delegator's account is the grant's delegate, this is a direct call: `authorizer` is `msg.sender`. Whatever drove that account to call, such as a sub-delegation it granted, is that account's own access control (see [Security Considerations](#security-considerations)). - Otherwise the executing account MUST be the grant's principal. Where the manager runs caveat hooks and keeps no record of the redeemer that the executor could ask for, the executor learns the redeemer from a caveat enforcer that it trusts by address and that records the redeemer for it, scoped to this spend. The executor MUST reject any other caller on this path before consulting any record. The enforcer MUST accept hook calls only from the delegation manager it trusts; a record anyone could write would name any redeemer. It MUST revert for an execution that is not a call to the executor's spend function in single-call default mode with no other mode bits set. For a call to that function whose `grantId` the executor's trusted registry does not know, it MUST write nothing. For any other `grantId`, it MUST revert unless the delegation carrying the caveat is the root of the chain, whose delegator performs the execution; that delegator is the principal the registry reports for the `grantId`; the delegation names the grant's `delegate` as its delegate; the redeemer is the grant's `delegate`; and the delegation carries the caveat exactly once. When all of these hold, it MUST record the redeemer. A record written lower in the chain would stay live from that hook until its own afterHook, through the hooks above it, the execution, and any callbacks, and might never be taken at all; a second copy of the caveat on the root would write the record again after a hook between the copies could have taken it. Either way, anyone who could then make that delegation's delegator call the executor could pay the same spend again. The enforcer MUST key the record on that `grantId`, `asset`, `amount`, `recipient`, and the principal. The record MUST NOT be usable outside the transaction that wrote it; transient storage ([EIP-1153](./eip-1153.md)) gives this directly. The enforcer MUST clear its record after the execution if the executor did not take it. The executor MUST look the record up under the `grantId` it was called with and under its caller, MUST clear it before calling `consume` or moving funds, so that one record produces at most one `consume`, and MUST treat a missing record as no authorization. `authorizer` is the recorded redeemer. Any other source of the redeemer MUST give the same properties: written only by the trusted manager, only for a redemption by the grant's `delegate` of the principal's own root delegation to it, at most once for each execution, bound to the exact spend and to the principal as the executing account, usable once, and confined to the transaction. An executor MUST NOT pass as `authorizer` an address it has not authenticated for this spend. When authentication produces nothing, the executor MUST revert rather than pass `address(0)` or any other placeholder. Passing the grant's delegate is correct only when it is the address the executor just authenticated, for example the address whose ERC-1271 validation succeeded. This specification does not define account adapters, permission compilation, or which mechanism an executor uses. For `asset == NATIVE`, movement is a native transfer of `amount` wei from the grant's principal. For any other asset, movement is one call to the asset's ERC-20 `transferFrom` (or an equivalent transfer function) requesting exactly `amount` raw units from the principal to `recipient`; a revert, a `false` return, or a malformed return is a failed movement. The executor MUST NOT substitute a wrapped native token for `NATIVE` or treat `address(0)` as `NATIVE`. An executor MUST NOT call `consume` with `asset == NATIVE` unless the same call moves `amount` wei out of the principal's balance, and MUST NOT pay a `NATIVE` spend from value supplied by its caller or from its own balance. An executor MAY read the principal's balance of the asset before and after the movement and revert if the decrease exceeds `amount`; it MUST NOT pass an observed balance change to `consume` in place of the requested `amount`. ## Rationale This proposal is the **terms** of a spend grant plus an on-chain registry that holds them with their **remaining**. The typed object, rendering, and JSON are the terms. The registry is the v1 store for terms, remaining, and revocations. Movement stays with an executor so existing ERC-20 contracts and native currency need not opt in. The funds stay in the principal's account until spent rather than moving to each delegate in advance. A delegate funded in advance holds a balance the principal cannot use elsewhere, needs top-ups and sweeps, and keeps that balance until it is recovered. Under a grant nothing is stranded or topped up, `revoke` is one transaction by the principal that moves nothing, and setting the principal's allowance to the executor to zero stops every grant on that executor at once. Every spend draws on one account, and `grantsOf` lists every grant against it. The movement comes from the principal's balance because that balance and the principal's allowance to the executor are the bound the principal sets outside the registry, the one `grantState` reports and the one a zero allowance removes; a draw on credit creates a liability bounded by a limit the lender sets, which neither can show. Limits enforced by an off-chain service can be read only through that service; a grant's terms and remaining are on chain, where the principal, the delegate, and any relying party read the same values, and they are public for the same reason. The cost is concentration: each delegate is bounded by its caps, but the principal's allowance to the executor, and the executor itself, reach the principal's whole balance, which is why [Security Considerations](#security-considerations) bounds that allowance and the executor's code. Grants are registered on chain rather than signed by the principal and handed to the delegate. A registered grant can be found: the principal and the delegate each list the grants between them, with the terms in force and what remains, from the registry rather than from records each keeps. Its caps change in place with usage carried over, so a lower limit counts what was already spent, with no replacement to size against earlier spend and no window that starts empty. The delegate holds only `grantId`, so no signed grant waits off chain for its first use, and the principal revokes by an identifier it can always read back from the registry. The cost is a transaction from the principal before the delegate can spend, where a signed grant cost nothing until its first use. Registration submitted by a third party with the principal's signature is left to a later extension. `grantId` is the EIP-712 digest of the registered terms so that every implementation derives the same identifier from the same terms, before or after registration, and so that such an extension can have the principal sign that digest. `BAD_SIGNATURE` keeps its number for that extension, and because a reason number never changes meaning. `update` changes everything but `principal`, `delegate`, and `windowSeconds`. The principal and the delegate are fixed because a grant is one principal's allowance to one delegate; a new delegate, as after a key rotation, is a new grant. The window is fixed because a registry may drop expired debits from storage, so a longer window could not be evaluated over them. `update` ignores `salt` and keeps the registration `salt`, because `salt` only chooses the identifier at registration and the identifier never changes. A lowering is still a transaction from the principal, pending and open to front-running like `revoke`, but on inclusion it applies against all usage so far, and no signed copy of the terms exists to disagree with the caps in force. A revoked `grantId` stays registered, so registering the same terms again reverts. A revocation therefore permanently ends every authorization and delegation that names the identifier, including ones the delegate signed but never submitted. For the same reason there is no `unrevoke`: a principal who wants the delegate to spend again registers a new grant, with a new `salt` if the terms are otherwise the same. The registry keeps a list of grant identifiers per principal and per delegate although its events carry the same identifiers, because rebuilding the lists from logs needs a scan from the registry's deployment, which range-limited log queries make slow or unavailable, while a view answers from state at one block. The lists only grow, so a position stays valid from one page to the next; revoked grants stay listed and readers filter them with `getGrant`. [ERC-7710](./eip-7710.md) standardizes `redeemDelegations` and leaves `_permissionContexts` opaque, determined by the specific implementation. Granting a delegation is out of scope for that interface. This proposal is the terms those contexts may compile to. It is not listed in `requires`, because a remaining store and a typed grant are useful without that redemption bus. [ERC-7715](./eip-7715.md) is wallet JSON-RPC `wallet_requestExecutionPermissions`. Its permission types are not an exhaustive list. A wallet may request a spend grant of this shape without this proposal claiming to extend 7715. [ERC-8226](./eip-8226.md) is a regulated agent mandate: one asset per mandate, per-transaction and cumulative caps, a required compliance provider, venue-agnostic `canExecute`, and `MandateReason` codes. Freeze is not revoke. Like this proposal it stores mandates on chain, but covering this proposal's case would change that model rather than extend it. Its cumulative counter does not reset on `extendMandate`, and a cap changes only by revoking and re-issuing, which starts usage at zero; here `update` changes a grant's caps in place and keeps its usage. Only one mandate may be active per agent, principal, and asset, while a principal here may register several grants to one delegate, even for the same asset, each with its own identifier and revocation. `type(uint256).max` means no limit there, while this proposal has no value that means unlimited; a cap set to the largest integer is only a large cap. `grantMandate` rejects a zero compliance provider, and general-purpose spend has none. Reason names in this proposal are ERC-8226's for the corresponding conditions (`OK`, `NONEXISTENT`, `NOT_YET_VALID`, `EXPIRED`, `REVOKED`, `OVER_TX_CAP`, `OVER_CUMULATIVE_CAP`). Discussion of asset-enforced spend on Magicians argued that general spend belongs at the account layer so existing ERC-20 contracts and native currency need not opt in, and that token hooks are for issuer-controlled assets. This proposal follows that split: the registry never moves funds, and tokens need not implement a spend hook. A widely deployed smart-wallet spend permission (not an ERC) is one token with a recurring period allowance; its batch form signs several such single-token permissions at once. Each permission in a batch keeps its own period, which resets at a boundary. This proposal puts up to sixteen assets in one grant with one identifier and one revocation, and uses a trailing lookback rather than a period reset. Native currency uses the [ERC-7528](./eip-7528.md) address rather than `address(0)`. ERC-7528 is Final and is the native identifier in some deployed spend-permission systems; other deployed wallet-permission systems use `address(0)` for native currency. This proposal uses the Final standard, and an adapter for a system that uses `address(0)` translates at its boundary. It also keeps `address(0)` available as an unambiguous "unset" value: a zero asset is always invalid, a zero `recipient` field only ever means "any" in `recipientMode == 1`, and a zero `recipient` argument to `consume` is always rejected. EIP-7702 accounts are controlled by their key for as long as the key exists: the key can replace or clear the delegation at any time. Accepting that key's ECDSA signature therefore grants nothing the key does not already hold. That is true of rule (a); rule (b) accepts whatever the delegated code's ERC-1271 accepts, as for any contract signer (see [Security Considerations](#security-considerations)). Without rule (a), an authorization signed by a delegate's key would change validity when the account adopts, changes, or clears a delegation, and delegated code that lacks ERC-1271 (or requires a nested format such as [ERC-7739](./eip-7739.md)) would silently invalidate every outstanding authorization. Ordinary contract signers keep ERC-1271 only, because a contract's owner key is not the contract. Trailing `lookback`: a UTC-day reset allows two full `maxPerWindow` spends across midnight. Expiry at age `== windowSeconds` is exact, independent of clock hour. `86400` is twenty-four hours, not "today". With a trailing window, spend frees up as each debit expires rather than at one reset time, so the caps and `rollingUsage` do not say when more becomes available; `liveDebits` returns each unexpired debit's expiry so a wallet can show it. The same list can be rebuilt from `GrantConsumed` logs and block timestamps, but a view answers from state at one block without log-range limits or reorg handling. `maxCount` bounds how many debits are returned; oldest-first truncation keeps the debits that free up soonest, so no offset is defined. It does not bound the cost of passing over expired debits the registry has not yet dropped: in the reference, after a full ring goes idle for longer than the window, every `liveDebits` and `rollingUsage` call reads up to 1024 slots until a `consume` or `evict` drops them. `assetCombine` is reserved rather than removed. A shared budget across assets ("spend this much across A or B") is useful, but the only oracle-free form, dividing each spend by that asset's own cap, is not how principals budget; they budget in a unit of account, which needs a price reference this specification does not define. Keeping the field fixed at `0` means a later version can define another mode without changing `encodeType`, the type hash, the rendering, or the JSON shape, and fail-closed validation means registries built to this version reject such grants rather than misread them. `consume` is restricted to an immutable executor because a public debit function would let any caller fill the window, exhaust caps, or grief `WINDOW_FULL`. The principal selects that executor by choosing the registry it registers with. The executor, not the registry, authenticates the delegate: the registry's caller is always the executor, and delegates authorize in different ways (a direct call, a signed authorization that someone else relays, a redemption through a delegation framework such as [ERC-7710](./eip-7710.md)). The registry still requires the executor to name the address its authentication produced and rejects anything but the grant's `delegate`. That catches an executor that authenticates a caller or signer but omits the comparison with the grant's delegate; it does not catch one that passes the grant's `delegate` without authenticating anyone. It also gives conformance tests a value to check. On the delegation-framework path the enforcer does not leave that comparison to `consume`: it accepts only the principal's own root delegation to the grant's `delegate`, redeemed by that delegate, because a grant is one principal's allowance to one delegate, and it refuses every other shape a delegation framework allows, such as a delegation open to any delegate or to another account that re-delegates, a redemption by a sub-delegate, or a delegation signed by anyone but the principal. Letting those shapes through to `consume` breaks down for an account that is one grant's principal and another grant's delegate: a delegation open to any delegate, carrying the caveat, that it signed for its own grants would let whoever redeemed it make the account spend, as delegate, under the grants others gave it, because the record is not consulted when the delegate's account is the caller. The record the enforcer writes is bound to the exact spend and to the executing account, cleared on use, and confined to one transaction, because the executor's caller on that path is the delegator's account, and a record that any call in the transaction could read, or that outlived a failed try-mode execution, would be a bearer authorization again. Verifying a per-spend delegate signature in the registry was not chosen: it would impose one mechanism on every executor and add replay-protection storage to the core, and it fits better as an executor profile. `check` runs the evaluation `consume` runs, so a wallet, relayer, or executor learns before submitting whether a spend would succeed and, if not, the reason `consume` would give; a separate set of rules for simulation could drift from the one that decides. That equivalence is why a registry cannot add a failure mode outside the reason table, such as a per-transaction lock: the per-call cap limits each call, and the window and lifetime caps bound what any number of calls in one transaction can spend. The revert encoding and the reason numbers are normative so that a caller decodes every registry's revert the same way and can compare it with `check`'s result. The caps bound the amount the executor requests, not the change in the principal's balance, because the request is the only quantity every executor controls and the same quantity the ERC-20 allowance bounds. A mandatory balance check was considered and not taken: it costs two balance reads on every spend, it rejects legitimate spends on tokens whose share-based accounting can debit a unit more than requested, and an elastic-supply balance changes with no transfer at all, so a balance change has no stable meaning for such a token. Every conformant executor therefore gives the same guarantee, a bound on requested amounts, and one that adds the optional check only rejects more. `consume` rejects a payee of zero, the principal, the registry, the executor, or the asset being spent in both modes. A zero payee burns or misattributes funds on tokens that allow it, a payment to the principal spends cap and allowance on a no-op, and the registry, the executor, and a token's own contract usually have no way to release what they receive. Code is checked only for the asset being spent: the check exists so that no debit is recorded against an address that plainly cannot be a token, which only the spent asset needs, while checking every listing on every spend would cost a cold account access per asset and let one mistaken address block the whole grant. The check excludes addresses with no code and EIP-7702 delegated accounts; it cannot tell a token from code that accepts any call. `GrantConsumed` indexes the principal and the recipient as well as `grantId`, because a principal's wallet has to find spends by its own address, and a payee has to watch for payments to itself; filtering by asset is an indexer convenience that can be done off chain, so `asset` is data. The terms carry no hash of their rendering. The rendering is a function of the terms and the domain, so a hash of it would commit to nothing the terms do not already determine, and a wallet displays what it derives from the fields in any case. The canonical text is kept so that every raw-value text record of a grant is byte-identical. An application that needs to bind a grant to something outside it, such as a parent grant or an off-chain terms document, can derive `salt` from a commitment to that data, for example `salt = uint256(keccak256(abi.encode(parentGrantId, index)))`, without a change to this specification. Sorted unique assets make the typed-data encoding canonical and prevent two disagreeing limits for one address. Fail-closed enumerations mean a future `recipientMode == 2` is invalid to old registries rather than silently treated as "any". `hashGrant` returns the identifier that registering given terms would assign, so a wallet can know it before the registration is included without its own implementation of the hashing rules. `update` and `revoke` revert for an identifier that is not registered, so a wrong identifier fails visibly instead of marking nothing. A non-normative [ERC-7730](./eip-7730.md) descriptor for the calldata of `register` and `update` is in [`spend-grant.json`](../assets/eip-8427/clear-signing/spend-grant.json), because what a principal approves is a transaction to the registry. It lets a wallet show the delegate, recipient, window, each asset's caps in that asset's units, and the validity dates, and it rejects terms whose `assetCombine` is not `0`. A descriptor is bound to specific registry deployments and cannot call `executor()`, so a wallet still has to look up and show the executor itself. The live-debit bound exists because exact rolling cannot be a single counter. Because `block.timestamp` does not decrease, debits are appended in timestamp order and expired debits are always the oldest ones, so an implementation can keep a running window sum and drop expired debits from the front before each check. The reference does this with a fixed ring of 1024 one-word debits (64-bit timestamp, 192-bit amount), so the cost of a `consume` does not grow with the number of live debits and slots are reused once the ring wraps. The cost does grow with the number of expired debits dropped in that call: after a full ring goes idle for longer than the window, the next `consume` drops up to 1024 entries at once. The next spend that succeeds pays that cost, and later spends return to the flat cost. `evict` lets anyone drop expired debits in bounded pieces beforehand, so that cost need not fall on one spend. 1024 is a reference storage bound, not a `maxCalls` in the terms. `usage.calls` is observational for the same reason. `grantState` includes the principal's balance and its allowance to the executor because what can be spent now is bounded by them as well as by the caps, and computing it in the registry gives every wallet the same answer from one call at one block. The reads are fail-soft because the asset is arbitrary code: a token that reverts, returns malformed data, or burns gas cannot make the grant's state unreadable, and its value is reported as unknown instead. The gas check before each read means an unknown value always reflects the asset's behavior, never a caller that supplied too little gas. ## Backwards Compatibility This proposal adds a new typed-data domain, JSON shape, and registry interface. It does not change consensus, [EIP-712](./eip-712.md), [ERC-1271](./eip-1271.md), or [ERC-20](./eip-20.md) token behavior. Existing tokens need not implement hooks. Native currency is identified by the [ERC-7528](./eip-7528.md) address, as in other ERC-7528 systems; `address(0)` never denotes native currency. ## Test Cases Golden vectors are in [`v1.json`](../assets/eip-8427/vectors/v1.json). They include domain separator, struct hash, digest (the `grantId`), and canonical rendering bytes. An implementation of the Specification reproduces those values. No additional requirements are defined here. ## Reference Implementation A non-normative Solidity reference lives under the [assets directory](../assets/eip-8427/). It is an aid to implementers. It includes the registry, a minimal executor that the delegate calls with a `grantId`, an executor that also accepts delegate-signed authorizations submitted by anyone, an executor that also accepts [ERC-7710](./eip-7710.md) redemptions, and the caveat enforcer whose records that executor reads, with tests that drive them through a manager of that shape. The Specification is authoritative. Hashing, rendering, JSON interchange, validation, registration, caps, rolling expiry, and the reason encoding are implementable from this document without those sources. ## Security Considerations For [ERC-20](./eip-20.md) assets, the principal's allowance to the executor is the authority that actually lets funds move; the grant bounds how the executor uses it. A principal SHOULD keep that allowance no higher than the sum of remaining budgets of outstanding grants on that executor, and wallets SHOULD show the allowance next to the grants it backs. An executor with a larger allowance can move more than any grant permits if the executor is faulty. Two asset entries can denote the same underlying balance, for example a chain whose native currency is also exposed through an ERC-20 interface at a different decimal scale. A grant that lists both has two independent budgets over one balance. Issuers SHOULD list only one identifier for such an asset; wallets SHOULD warn when a grant lists a known alias pair. The code check at `consume` passes code that accepts any call, such as a proxy whose implementation has no code or a contract with an empty fallback, and a spend of such an asset can record a debit that moved nothing, so a wallet SHOULD confirm that a listed asset answers `balanceOf` and `decimals` before the principal registers or updates a grant that lists it. `grantState` reports what the asset's `balanceOf` and `allowance` return, so a token can report any values, and `spendableNow` is only as reliable as the token. The gas stipend, the one-word copy, and the fail-soft reads keep a token from making the view revert or from using more than the stipend on each read. The registry never moves funds. Safety of the principal's assets depends on the executor calling `consume` and moving funds within one call that reverts if either step fails. A dishonest executor that the principal bound by registering with that registry can move value without a matching debit, or debit without moving. Choosing a registry is choosing an executor. Wallets that omit `executor()` from the display before registration hide that binding. The registry fixes the executor's address, not its code. An executor that is an upgradeable proxy, has an owner or admin function, is an externally owned account, or is an EIP-7702 delegated account can change what it does after the principal registers a grant, and whoever controls it holds every principal's approval to it; the same applies to any contract the executor trusts by address, such as a delegation manager or the caveat enforcer whose records it reads. For `NATIVE`, the account adapter's authority to the executor plays the role of the ERC-20 allowance, and nothing caps it unless the adapter does. An executor SHOULD have no admin and no upgrade path, and a wallet SHOULD show, with `executor()`, whether that address has code, is an EIP-7702 delegation designator, or is a proxy it recognizes. The executor in turn relies on its registry, which tells it whose funds a grant spends and who may authorize it: the registry's principal check at registration and its cap and revocation checks are all that stand between a principal's approval and a grant the principal never registered, so an executor that trusts several registries exposes every principal's approval to the weakest of them. Grants are not private. A grant's terms are public from its registration, in calldata, in `GrantRegistered`, and in the registry's state; every update and spend is linked to it by `grantId`; and the lists link every grant to its principal and its delegate. Anyone can follow a delegate's spending under a grant, see whom it pays, and compute what remains. `salt` distinguishes grants but hides nothing, and a `salt` derived from public data, such as a parent grant's identifier (see [Rationale](#rationale)), links the grant to that data. A principal who needs payments not to be linkable to one another uses separate grants and, where the addresses themselves link them, separate addresses. A `grantId` is not secret: the registry lists it and its events carry it. The registry sees only the executor as its caller, so the delegate binding is exactly as strong as the executor's authorization check; `authorizer` catches an executor that authenticates a caller or signer but omits the comparison with the grant's `delegate`; it does not catch one that passes the delegate without authenticating anyone. An executor that treats knowledge of a `grantId` as authority lets anyone spend under the grant: | `recipientMode` | What a third party can do under the grant | | --- | --- | | `0` | Pay the grant's recipient at times the delegate did not choose (if the third party is that recipient, it is paying itself), exhaust the window and lifetime caps, or fill the live-debit bound with minimal debits | | `1` | Send the remaining budget to itself | An executor that lets one delegate-signed authorization succeed more than once lets anyone who has seen it repeat that payment, to the recipient the delegate named, until the caps are exhausted: the `recipientMode` `0` exposure above, whatever the grant's mode. An unused delegate authorization without a deadline can run whenever the grant's terms allow it until the grant is revoked; expiry does not end it, because an `update` can extend `validUntil`, and the delegate cannot withdraw it except through the executor. A delegate-signed authorization names `grantId`, not a version of the terms, so an `update` applies to every unused authorization: one that failed, or would fail, under the earlier terms, for example by exceeding a cap or naming a recipient those terms excluded, succeeds once an update allows it. A principal who raises a cap, extends validity, or widens the recipients enlarges what every unused authorization from the delegate can do. A signed authorization is public once broadcast, and one whose transaction reverted or was dropped is still unused: its calldata may be on chain and its nonce was not recorded, so anyone can submit it later, once it would succeed. A delegate that replaces a failed authorization with a new one for the same payment can pay the recipient twice unless it first invalidates the old nonce and confirms the old authorization did not execute; a short deadline bounds how long a failed authorization stays usable. When the delegate is a contract, its own access control is the delegate binding. The executor authenticates the contract and the registry compares only its address, so a delegate contract that lets its caller choose the grant, amount, or recipient (for example one contract acting for many principals, a forwarder, or a contract with a general call function), or whose ERC-1271 accepts signers the principal did not intend, gives whoever can make it call the exposure in the table above. A principal who names a contract delegate relies on that contract's access control as it relies on the executor's. A delegate account that performs an [ERC-7710](./eip-7710.md) execution for a sub-delegate it appointed is this case: the executor sees the delegate account, `consume` accepts it, and the sub-delegation is that account's own policy. Such a delegation lets its redeemer make the account call the executor for any grant the account can exercise as delegate, not only the grants the account had in mind, so the account restricts the grant, asset, amount, or recipient with calldata caveats of its own. An account that signs a delegation open to any delegate under which its redeemer can make the account call the executor for any grant lets anyone spend under every grant that names that account as delegate, including grants others register later, since any principal can register a grant naming any delegate. On the delegation-framework path the record a caveat enforcer writes is the delegate binding. Without the requirements in [Executor](#executor), anyone could write a record, a record could be used twice or outlive its transaction, and a middle delegator in the chain could turn the delegate's one redemption into several spends. The executor trusts the enforcer, and through it the delegation manager, by address. One executor serves every principal that registers grants with its registry, and those principals approve the executor itself. An executor that moved funds from any account other than the grant's principal could therefore spend one principal's balance under another principal's grant; the movement source is fixed to the grant's principal in [Executor](#executor) for that reason. The executor is also the ERC-20 spender for all of them, so a token that blocklists the spender can stop every grant for that token on that registry at once. The registry and executor cannot be changed, so resuming means new grants on a new registry. `consume` does not inspect balances: it records the `amount` the executor requested, and the caps bound requested amounts, as the principal's allowance does. Three kinds of ERC-20 make the principal's balance change differ from recorded spend. A token that charges the sender a fee on top of the requested amount lets the principal's balance fall by more than the caps over the grant's life, by the fee; a conformant executor is not required to detect this, because the spend it requested was within the caps. A token that deducts a fee from the delivered amount, the common fee-on-transfer pattern, debits the principal exactly the requested amount and short-pays the recipient, which does not touch the caps. An elastic-supply token changes the principal's balance with no transfer at all. A wallet SHOULD warn when a listed asset is known to charge transfer fees or to rebase, and SHOULD say that the caps are raw units requested from the token, not balance changes. An executor that adds the optional balance check in [Executor](#executor) protects the principal from the first kind, at the cost of two balance reads per spend and of rejecting spends on tokens whose rounding can debit a unit more than requested. This concerns ERC-20 assets: a native transfer of `amount` wei is exact, and the authority of a `NATIVE` account adapter is covered above. Revocation is permanent and takes effect only when the `revoke` transaction is included; it does not pause the executor. A delegate that sees a pending `revoke` in a public mempool, or anyone holding an unused authorization from that delegate, can place spends ahead of it, up to what is spendable at that moment in each asset (see [Registry](#registry)). An `update` that lowers a cap, shortens validity, or narrows the recipients is pending in the same way: the earlier terms apply until it is included, and from then on the new caps apply against everything already spent. A grant reserves nothing: until a spend is included, the principal can revoke, update, lower the allowance, or move the balance, and other spends or grants can use what the views showed, so a recipient that delivers before the spend is included carries that risk. There is no admin to freeze a stolen delegate; the principal revokes its grants, and remaining caps bound a stolen delegate until then. Revocation needs no stored record of the grant: `grantsOf` lists every grant a principal has registered, and `revoke` takes only the identifier. There is no revoke-all, but setting the principal's ERC-20 allowance to the executor to zero, or disabling a `NATIVE` account adapter, stops every grant on that executor at once. Disabling a delegation in a delegation framework does not revoke a grant; the grant stays live through any other delegation that carries it and any other mechanism the executor accepts. Anyone can register a grant naming any address as its delegate, so `grantsTo` can hold any number of grants the delegate never asked for, each spending only its own principal's assets. A wallet or agent that reads a delegate's grants SHOULD read `grantsTo` in bounded pages and filter it by principal, since a listed grant shows only that its principal registered it. Code-bearing signers other than EIP-7702 accounts are ERC-1271 only. An implementation that falls back to ECDSA when `isValidSignature` fails would treat a contract with an `owner` key as that key. The EIP-7702 exception is safe only because the designator identifies an account whose key already controls it; implementations MUST match the exact 23-byte designator rather than any code that begins with `0xef`. ERC-1271 is evaluated at execution, so a delegate that rotates its validation logic can invalidate its outstanding authorizations without the executor's help. An EIP-7702 delegate cannot invalidate authorizations its key signed by changing its delegation; it invalidates their nonces. For a contract principal, the account's call policy is its grant policy: any signer or module that can make the account call `register` or `update`, whether an owner key, a session key, a passkey, or a guardian, can register a grant to any delegate with any caps and `recipientMode == 1`, or raise an existing grant's caps, and that grant draws on every allowance the principal has already given the executor. An account that scopes session keys SHOULD keep calls to the registry, like any call outside the key's purpose, out of what those keys may make; a principal's exposure through such a key is bounded only by the allowance. The 1024-live-debit bound (or any similar bound) is a grief surface: many small in-window consumes can fill the window and force `WINDOW_FULL` until the oldest debit expires. Only the executor can call `consume`, and a conformant executor spends only with the delegate's authorization, so the grief requires the delegate itself or a non-conformant executor. This is an intentional fail-closed behavior. `block.timestamp` is the chain's clock, not wall-clock time; window expiry, `validAfter`, `validUntil`, and the `expiresAt` values from `liveDebits` are all measured on it. On some rollups the sequencer sets it within wide bounds, so a trailing window is exact in block time but only as close to real time as the chain keeps its clock. Short `windowSeconds` values are the most exposed; lifetime caps are not affected. Reentrant `consume` during a token hook in the executor's movement can apply several per-call amounts in one transaction if remaining allows. The per-call cap limits each call, not the transaction. The registry cannot be paused or upgraded. A bug in remaining arithmetic is permanent for that deployment. A new registry is a new domain, so its grants have new identifiers and need new registrations. A registry MUST NOT be redeployed at an address a previous registry occupied on a chain whose state was reset but kept its chain ID: registering terms identical to an earlier grant's would give the same `grantId`, and with an executor again at the previous executor's address, whose recorded nonces the reset erased, every authorization the delegate signed for that grant, including ones already spent and ones for a grant since revoked, would be valid again. Registering terms identical to a registered grant's, revoked or not, reverts with `GrantExists`, so no registration resets a grant's usage or revives a revoked grant; distinct grants need a distinct `salt` or a distinct field. ## Copyright Copyright and related rights waived via [CC0](../LICENSE.md).