IAllowanceManager

Author: Ultrasound Labs

Interface for the AllowanceManager contract responsible for time-boxed pull-allowances that subaccounts (Safes) can spend. It supports batch EIP-712(x) signing across chains.

Functions

bootstrapAllowance

Bootstrap an allowance once immediately after AllowanceHolder deployment.

Can only be called by the canonical AllowanceHolder for (owner, token) and only when nonce == 0. After a successful call, allowanceNonces[owner][subaccount][token] will be incremented to 1 so that any subsequent changes require a signed setAllowances().

function bootstrapAllowance(address owner, address subaccount, address token, uint256 amount, uint256 timeframe)
    external;

Parameters

Name	Type	Description
`owner`	`address`	The owner of the allowance (signer of the permit given to the holder).
`subaccount`	`address`	Subaccount that the allowance applies to.
`token`	`address`	ERC-20 token address.
`amount`	`uint256`	Allowance amount.
`timeframe`	`uint256`	Time window in seconds for the allowance resets.

commitHolder

Commits the expected AllowanceHolder address for an (owner, token) pair before deployment.

Must be called exactly once per (owner, token) pair and before the first bootstrapAllowance call. The first bootstrap must come from the committed holder; after a successful bootstrap the commit is cleared so future holders (for different subaccounts) can be deployed without an extra commit.

Access control: This function MAY only be called by the canonical SubaccountFactory (address set in the AllowanceManager constructor). Any call from another address MUST revert.

function commitHolder(address owner, address token, address holder) external;

Parameters

Name	Type	Description
`owner`	`address`	The token owner that will grant allowance.
`token`	`address`	The ERC-20 token the holder will manage.
`holder`	`address`	The deterministic address where the AllowanceHolder will be deployed (CREATE2 pre-image).

registerHolder

Registers an additional AllowanceHolder address after the canonical one has been initialised.

Must be called by the canonical SubaccountFactory before the new holder constructor executes so that the holder can successfully call bootstrapAllowance. Skips commit-reveal checks and only pre-authorises the address.

function registerHolder(address holder) external;

Parameters

Name	Type	Description
`holder`	`address`	The deterministic address of the new AllowanceHolder.

setAllowances

Sets allowances for a batch of subaccounts

function setAllowances(address owner, AllowanceRequestBatch calldata requests, bytes calldata signature) external;

Parameters

Name	Type	Description
`owner`	`address`	The owner of the subaccounts
`requests`	`AllowanceRequestBatch`	The AllowanceRequestBatch struct containing the requests
`signature`	`bytes`	The EIP-712x (EIP-712 with chainId = 1) signature of the owner

spendAllowance

Spends an allowance for the caller

function spendAllowance(address owner, address token, uint256 amount) external;

Parameters

Name	Type	Description
`owner`	`address`	The owner of the subaccount
`token`	`address`	The token to spend the allowance for
`amount`	`uint256`	The amount to spend

holderAddress

Deterministically computes the canonical AllowanceHolder address for a pair (owner, token).

function holderAddress(address owner, address token) external view returns (address holder);

Parameters

Name	Type	Description
`owner`	`address`	The token owner.
`token`	`address`	The ERC-20 token.

Returns

Name	Type	Description
`holder`	`address`	The predicted holder address (or address(0) if unknown).

allowances

Mapping to track allowances for subaccounts.

function allowances(address owner, address subaccount, address token) external view returns (Allowance memory);

Parameters

Name	Type	Description
`owner`	`address`	The owner of the subaccount.
`subaccount`	`address`	The subaccount that the allowance is set for.
`token`	`address`	The token that the allowance is set for.

Returns

Name	Type	Description
`<none>`	`Allowance`	allowance The allowance struct.

allowanceNonces

Mapping to track allowance nonces for subaccounts.

function allowanceNonces(address owner, address subaccount, address token) external view returns (uint256 nonce);

Parameters

Name	Type	Description
`owner`	`address`	The owner of the subaccount.
`subaccount`	`address`	The subaccount that the allowance is set for.
`token`	`address`	The token that the allowance is set for.

Returns

Name	Type	Description
`nonce`	`uint256`	The nonce of the allowance.

permit2

The Permit2 contract address

function permit2() external view returns (address permit2Addr);

Returns

Name	Type	Description
`permit2Addr`	`address`	The Permit2 contract address.

allowanceRequestTypehash

EIP-712(x) typehash for the AllowanceRequest struct (per-subaccount)

function allowanceRequestTypehash() external pure returns (bytes32 typeHash);

Returns

Name	Type	Description
`typeHash`	`bytes32`	The struct type-hash.

allowanceRequestBatchTypehash

EIP-712(x) typehash for the AllowanceRequestBatch struct (per-subaccount)

function allowanceRequestBatchTypehash() external pure returns (bytes32 typeHash);

Returns

Name	Type	Description
`typeHash`	`bytes32`	The struct type-hash.

hashAllowanceRequestBatch

Computes the EIP-712 struct hash for a batch of allowance requests.

function hashAllowanceRequestBatch(AllowanceRequestBatch calldata batch) external pure returns (bytes32 structHash);

Parameters

Name	Type	Description
`batch`	`AllowanceRequestBatch`	The AllowanceRequestBatch struct to hash.

Returns

Name	Type	Description
`structHash`	`bytes32`	The EIP-712 struct hash.

Events

AllowanceSet

Emitted when a new allowance is set.

event AllowanceSet(
    address indexed owner, address indexed subaccount, address indexed token, uint256 amount, uint256 timeframe
);

Parameters

Name	Type	Description
`owner`	`address`	The owner of the subaccount.
`subaccount`	`address`	The subaccount that the allowance is set for.
`token`	`address`	The token that the allowance is set for.
`amount`	`uint256`	The amount of the allowance.
`timeframe`	`uint256`	The timeframe of the allowance.

AllowanceSpent

Emitted when an allowance is spent.

event AllowanceSpent(address indexed owner, address indexed subaccount, address indexed token, uint256 amount);

Parameters

Name	Type	Description
`owner`	`address`	The owner of the subaccount.
`subaccount`	`address`	The subaccount that the allowance is spent for.
`token`	`address`	The token that the allowance is spent for.
`amount`	`uint256`	The amount of the allowance that was spent.

Errors

AllowanceExceeded

Emitted when an allowance is exceeded.

error AllowanceExceeded();

Structs

AllowanceRequest

Struct for a single allowance request.

struct AllowanceRequest {
    address subaccount;
    address token;
    uint256 amount;
    uint256 timeframe;
    uint256 nonce;
}

AllowanceRequestBatch

Struct for a batch of allowance requests.

struct AllowanceRequestBatch {
    AllowanceRequest[] requests;
    uint256[] chainIds;
}

Allowance

Struct for an allowance.

struct Allowance {
    uint256 amount;
    uint256 timeframe;
    uint256 spent;
    uint256 resetsAt;
}