Allowances

Allowances are a mechanism for enforcing spending limits or other kind 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 be updated 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 call data, 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

It's also possible to enforce a rate limit on the number of calls to a function using a CallWithinAllowance condition. Each call to the function will decrement the allowance balance by 1.