Allowances

Allowances serve as a mechanism for enforcing spending limits or other types of quotas for individual roles.

Structure

Allowances are centrally defined and can be referenced from conditions.

Each allowance is stored as a tuple of the following shape:

struct Allowance {
  uint128 refill;
  uint128 maxRefill;
  uint64 period;
  uint128 balance;
  uint64 timestamp;
}

period – Duration of the refill interval in seconds, 0 for one-time allowance

refill – Amount that will be refilled per interval

timestamp – Timestamp of the last interval refilled for

maxRefill – Max accrual amount, refilling stops once the unused allowance balance hits this value

balance – Unused allowance that can be spent

All fields can be manually updated.

Upon consumption of an allowance, the balance and timestamp fields will automatically:

• Update the balance to reflect the accrual since the last refill
• Update the refill timestamp to the current interval’s timestamp
• Subtract the consumed amount from the balance

Usage

There are two different ways allowances can be used:

Allowance on a uint field or Ether value

To define an allowance on any uint field in the transaction calldata, use a WithinAllowance condition.

To define an allowance on the Ether value sent with the transaction, use WithinAllowance with Encoding.EtherValue parameter type.

Call Rate Limits

To enforce a rate limit on the number of calls to a function, use a CallWithinAllowance condition. Each call to the function will decrement the allowance balance by 1.

Consumption Tracking

Allowances consumed during condition evaluation are tracked per transaction and only settled after the transaction has been successfully executed. If the condition evaluation fails or the underlying call reverts, no allowance balances are updated. This ensures that allowances accurately reflect actual spending rather than attempted spending.

Denominated Allowances

For use cases where a single allowance should cover multiple tokens, allowances can be combined with price adapters to convert token amounts into a shared denomination before consumption. This enables unified spending caps across different assets — for example, a single USD-denominated budget that applies regardless of which token is being transferred.