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 three different ways allowances can be used:

Allowance on a uint field

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

Allowance on the Ether value

To define an allowance on the Ether value sent with the transaction, use an EtherWithinAllowance condition.

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.