Allowance

The Safe Allowance Module is a powerful tool designed to enable users to automate token transfers securely. It provides a flexible framework that allows account owners to delegate specific rights and permissions to other accounts or contracts, ensuring that funds can be transferred or utilized according to predefined conditions.

This module does not manage allowances in the traditional sense of ERC20 token contracts. Instead, it provides a method for granting authorization of specific accounts to a delegate: (an account or a smart contracts), allowing them to interact with the Main Account on behalf of the user. It ensures secure and controlled access to funds while facilitating automated transactions.

By leveraging the Safe Allowance Module, wallet developers can implement sophisticated financial operations with ease. Whether it's managing delegated funds for multiple users, automating payment processes or delegating to smart contracts for various usecases.

Use Cases

Recurring Transfers: Automate periodic transactions for reccuring transfers. Users can define the amount, frequency, duration, and receipients.

Subscriptions: Set up automatic payments for subscriptions, utility bills, or membership fees.

Dollar-Cost Averaging (DCA): Facilitate DCA by delegating allowances to swap contracts.

And More.. by delegating to smart contracts for specific needs.

Audits

• Ackee Audit 2024
• GnosisSafe Audit 2020

Usage

Install

npm

npm i abstractionkit

yarn

yarn add abstractionkit

info

The Allowance module is currently in an experimental release under abstractionkit@0.2.1

Import

import { AllowanceModule } from "abstractionkit";

How to use

AbstractionKit provides two types of methods for the Allowance Module

1. The recommended methods that offer simplified interfaces. These are under Methods.
2. Those prefixed with createBase, which match the exact contract method names and paramaters. These are under Advanced Methods.

While createBase methods allow direct interaction with the contract, they can be confusing for developers due to the multiple options and paramaters involved. The recommended methods improves usability by providing clearer and more intuitive method names and input parameters.

tip

If you're looking for a code example, take a look at Allowance Module tests

1. Initialize the Module

const allowanceModule = new AllowanceModule();

2. Enable the Module

const enableModuleMetaTransaction = allowanceModule.createEnableModuleMetaTransaction(sourceAccountAddress);

3. Add Delegate

const addDelegateMetaTransaction = 
    allowanceModule.createAddDelegateMetaTransaction(
        delegateAddress,
    );

4. Set Allowance

In the example below, we show how to set a reccuring allowance through createRecurringAllowanceMetaTransaction. You can also use one time allowences via createOneTimeAllowanceMetaTransaction

const setAllowanceMetaTransaction = 
    allowanceModule.createRecurringAllowanceMetaTransaction(
        delegateAddress, // The address of the delegate to whom the recurring allowance is given.
        allowanceToken, // The address of the token for which the allowance is set. 
        1, // The amount of the token allowed for the delegate.
        3, // The time period (in minutes) after which the allowance resets.
        0 // The delay in minutes before the allowance can be used.
    );

5. Create UserOperation

We batch all three MetaTransactions into a single UserOperation with createUserOperation. From there, you can continue the normal flow of signing and submiting the UserOperation onchain.

const userOperation =
    await allowanceSourceAccount.createUserOperation(
        [enableModuleMetaTransaction, addDelegateMetaTransaction, setAllowanceMetaTransaction],
        jsonRpcNodeProvider,
        bundlerUrl,
    );

6. The Delegate execute the Allowance

Once the allowance is set and the conditions are met, the delegate can execute the token transfer. The delegate can be an automated service, an EOA (Externally Owned Account), or a smart contract.

const allowanceTransferMetaTransaction =
    allowanceModule.createAllowanceTransferMetaTransaction(
        sourceAccountAddress, // The safe address from which the allowance is being transferred
        allowanceToken,
        transferRecipient, // The recipient address of the allowance transfer.
        2, // The amount of tokens to be transferred.
        delegateAddress, // The delegate address managing the transfer.
    );

info

Candide Atelier offers an automation tool to execute delegated allowances. Contact us directly for Beta access.

Methods

createEnableModuleMetaTransaction

Creates a MetaTransaction to enable a specified module for a Safe account. This transaction allows the specified account to interact with the module.

Param Types

key	type	description
accountAddress	string	The target Safe Account address to enable the module for.

Return Types

key	type	description
MetaTransaction	key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	MetaTransaction is the type of transaction to construct a Safe operation.

createAddDelegateMetaTransaction

Creates a MetaTransaction that allows adding a delegate to the account. This enables the specified delegate to perform actions on behalf of the account.

Param Types

key	type	description
delegate	string	The delegate address that should be added.

Return Types

key	type	description
MetaTransaction	key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	MetaTransaction is the type of transaction to construct a Safe operation.

createOneTimeAllowanceMetaTransaction

Creates a MetaTransaction that sets a one-time allowance for a delegate to use specified tokens. This transaction can be scheduled to start after a certain period.

Param Types

key	type	description
delegate	string	The address of the delegate to whom the allowance is given.
token	string	The address of the token for which the allowance is set.
allowanceAmount	bigint	The amount of the token allowed for the delegate.
startAfterInMinutes	bigint	The delay in minutes before the allowance can be used.

Return Types

key	type	description
MetaTransaction	key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	MetaTransaction is the type of transaction to construct a Safe operation.

createRecurringAllowanceMetaTransaction

Creates a MetaTransaction that sets a recurring allowance for a delegate to use specified tokens. This transaction can be scheduled to start after a certain period and will automatically reset after the specified validity period.

Param Types

key	type	description
delegate	string	The address of the delegate to whom the recurring allowance is given.
token	string	The address of the token for which the allowance is set.
allowanceAmount	bigint	The amount of the token allowed for the delegate.
recurringAllowanceValidityPeriodInMinutes	bigint	The time period (in minutes) after which the allowance resets.
startAfterInMinutes	bigint	The delay in minutes before the allowance can be used.

Return Types

key	type	description
MetaTransaction	key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	MetaTransaction is the type of transaction to construct a Safe operation.

createAllowanceTransferMetaTransaction

Creates a MetaTransaction that allows using the allowance to perform a transfer. This transaction enables the specified delegate to transfer tokens from the account's allowance.

Param Types

key	type	description
allowanceSourceSafeAddress	string	The safe address from which the allowance is being transferred.
token	string	The token address being transferred.
to	string	The recipient address of the allowance transfer.
amount	bigint	The amount of tokens to be transferred.
delegate	string	The delegate address managing the transfer.
overrides	key type description delegateSignature string The signature of the delegate. Optional. paymentToken string An optional payment token address. Defaults to the zero address. paymentAmount bigint The amount of the payment token to be transferred. Required if paymentToken is specified.	Optional overrides including delegate signature, payment token, and payment amount.

Return Types

key	type	description
MetaTransaction	key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	MetaTransaction is the type of transaction to construct a Safe operation.

createRenewAllowanceMetaTransaction

Creates a MetaTransaction that allows renewing (resetting) the allowance for a specific delegate and token. This transaction enables the account to extend the delegate's allowance without having to delete and recreate it.

Param Types

key	type	description
delegate	string	The address of the delegate whose allowance should be reset.
token	string	The address of the token for which the allowance is set.

Return Types

key	type	description
MetaTransaction	key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	MetaTransaction is the type of transaction to construct a Safe operation.

createDeleteAllowanceMetaTransaction

Creates a MetaTransaction that allows removing the allowance for a specific delegate and token. This transaction sets all values except the nonce to 0, effectively revoking the delegate's permission to use the allowance.

Param Types

key	type	description
delegate	string	The address of the delegate whose allowance should be removed.
token	string	The address of the token for which the allowance is set.

Return Types

key	type	description
MetaTransaction	key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	MetaTransaction is the type of transaction to construct a Safe operation.

Helpers

getDelegates

Retrieves a list of delegates associated with a specified Safe account. This function allows pagination to manage large sets of delegates.

Param Types

key	type	description
nodeRpcUrl	string	The JSON-RPC API URL for the target chain.
safeAddress	string	The target account address.
overrides	key type description start bigint The starting point for fetching delegates. Defaults to 0. maxNumberOfResults bigint The maximum number of results to return. If specified, overrides pagination.	Optional parameters for pagination.

Return Types

key	type	description
Delegate Addresses	string[]	A promise that resolves to a list of delegate addresses.

getTokensAllowance

Retrieves the allowance for a specific delegate and token associated with a specified Safe account. This function returns an object containing details about the allowance, including the amount, spent, reset time, last reset time, and nonce.

Param Types

key	type	description
nodeRpcUrl	string	The JSON-RPC API URL for the target chain.
safeAddress	string	The target account address.
delegate	string	The address of the target delegate.
token	string	The address of the token for which the allowance is being queried.

Return Types

key	type	description
Allowance	key type description amount bigint The total allowance amount. spent bigint The amount spent from the allowance. resetTimeMin bigint The time in minutes after which the allowance resets. lastResetMin bigint The time in minutes when the allowance was last reset. nonce bigint The nonce for the allowance.	A promise that resolves to the allowance details for the specified token.

getTokens

Retrieves the delegated tokens for a specific delegate associated with a Safe account.

Param Types

key	type	description
nodeRpcUrl	string	The JSON-RPC API URL for the target chain.
safeAddress	string	The target account address.
delegate	string	The address of the target delegate.

Return Types

type	description
string[]	A promise that resolves to a list of delegated token addresses.

IsModuleEnabled

Checks if a specified module is enabled for a given Safe account. This function returns a boolean indicating the module's status.

See the method IsModuleEnabled in the Safe Account.

createRemoveDelegateMetaTransaction

Creates a MetaTransaction that allows removing a delegate from the Safe account. It can also remove allowances if specified.

Param Types

key	type	description
delegate	string	The delegate address that should be removed.
removeAllowances	boolean	Indicator if allowances should also be removed. Set to true unless this causes an out of gas.

Return Types

key	type	description
MetaTransaction	key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	MetaTransaction is the type of transaction to construct a Safe operation.

Advanced Methods

createBaseSetAllowanceMetaTransaction

Creates a MetaTransaction to update the allowance for a specified token. This can only be done via a Safe transaction.

Param Types

key	type	description
delegate	string	The address of the delegate whose allowance should be updated.
token	string	The address of the token for which the allowance is set.
allowanceAmount	bigint	The amount of the token allowed for the delegate.
resetTimeMin	bigint	Time in minutes after which the allowance resets.
resetBaseMin	bigint	Time interval to increase the reset time.

Return Types

key	type	description
MetaTransaction	key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	MetaTransaction is the type of transaction to construct a Safe operation.

createBaseExecuteAllowanceTransferMetaTransaction

Creates a MetaTransaction that allows using the allowance to perform a transfer.

Param Types

key	type	description
safeAddress	string	The Safe address whose funds should be used.
token	string	The token contract address being transferred.
to	string	The recipient address of the token transfer.
amount	bigint	The amount of tokens to be transferred.
paymentToken	string	The token that should be used to pay for the execution of the transfer.
payment	bigint	The amount to be paid for executing the transfer.
delegate	string	The delegate whose allowance should be updated.
delegateSignature	string	Signature generated by the delegate to authorize the transfer.

Return Types

key	type	description
MetaTransaction	key type description to string To address, or the the target contract address for the transaction value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) data BytesLike The call data for the transaction operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional)	MetaTransaction is the type of transaction to construct a Safe operation.

Advanced Helpers

baseGetDelegates

Retrieves a list of delegates associated with a specific Safe account. It supports pagination to manage large results.

Param Types

key	type	description
nodeRpcUrl	string	The JSON-RPC API URL for the target chain.
safeAddress	string	The target account address.
start	bigint	The starting point for fetching delegates.
pageSize	bigint	The number of delegates to return in one call.

Return Types

key	description	type
{ results: string[], next: bigint }	A promise that resolves to an object containing the list of delegate addresses and the next starting point for pagination.	key type description results string[] A list of delegate addresses. next bigint The next starting point for pagination. Returns 0 if there are no more delegates.