Contents

• IAllowanceHolder
• IAllowanceManager
• ISafeTx

IAllowanceHolder

Git Source

Author: Ultrasound Labs

Interface for AllowanceHolder contracts which can pull tokens from an owner according to an allowance granted off-chain (e.g. via ERC-20 permit).

Functions

pull

Transfers amount of token() from the owner() directly to subaccount.

Can only be called by allowanceManager().

function pull(address subaccount, uint256 amount) external;

Parameters

owner

Returns the token owner whose funds can be pulled.

function owner() external view returns (address ownerAddr);

Returns

token

Returns the ERC-20 token managed by this holder.

function token() external view returns (address tokenAddr);

Returns

allowanceManager

Returns the AllowanceManager that is authorised to call pull.

function allowanceManager() external view returns (address manager);

Returns

IAllowanceManager

Git Source

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

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

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

setAllowances

Sets allowances for a batch of subaccounts

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

Parameters

spendAllowance

Spends an allowance for the caller

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

Parameters

holderAddress

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

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

Parameters

Returns

allowances

Mapping to track allowances for subaccounts.

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

Parameters

Returns

allowanceNonces

Mapping to track allowance nonces for subaccounts.

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

Parameters

Returns

permit2

The Permit2 contract address

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

Returns

allowanceRequestTypehash

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

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

Returns

allowanceRequestBatchTypehash

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

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

Returns

hashAllowanceRequestBatch

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

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

Parameters

Returns

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

AllowanceSpent

Emitted when an allowance is spent.

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

Parameters

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;
}

ISafeTx

Git Source

Author: Ultrasound Labs

Interface that exposes the SafeTx struct used across the project for meta-transactions.

Structs

SafeTx

struct SafeTx {
    address to;
    uint256 value;
    bytes data;
    uint8 operation;
    uint256 safeTxGas;
    uint256 baseGas;
    uint256 gasPrice;
    address gasToken;
    address refundReceiver;
    uint256 nonce;
}

Contents

• LengthMismatch
• EIP712x
• SiglessTransactionExecutor

LengthMismatch

Git Source

Centralized custom errors shared across multiple contracts.

Thrown when two arrays expected to be equal in length differ.

This file defines reusable error types to avoid duplicate declarations across source files.

error LengthMismatch();

EIP712x

Git Source

Authors: Ultrasound Labs (https://github.com/ultrasoundlabs), Modified from Solady (https://github.com/vectorized/solady/blob/main/src/utils/EIP712.sol), Modified from Solbase (https://github.com/Sol-DAO/solbase/blob/main/src/utils/EIP712.sol), Modified from OpenZeppelin (https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/utils/cryptography/EIP712.sol)

Modified EIP-712 contract with chainId hardcoded to 1 for multi-chain signatures.

WARNING: If you are using this for multi-chain signatures, please make sure that the payload you sign handles chainId-based replay protection internally! EIP712x removes this replay protection specifically so that payloads handle it on their end.

State Variables

_HARDCODED_CHAIN_ID

We hardcode chainId to 1 so that signatures generated for Ethereum Mainnet can be verified on other chains using this verifier contract. Why 1? - Because all EVM wallets have Ethereum Mainnet supported by default.

uint256 public constant _HARDCODED_CHAIN_ID = 1;

_DOMAIN_TYPEHASH

keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)").

bytes32 internal constant _DOMAIN_TYPEHASH = 0x8b73c3c69bb8fe3d512ecc4cf759cc79239f7b179b0ffacaa9a75d522b39400f;

_DOMAIN_TYPEHASH_SANS_CHAIN_ID

keccak256("EIP712Domain(string name,string version,address verifyingContract)"). This is only used in _hashTypedDataSansChainId.

bytes32 internal constant _DOMAIN_TYPEHASH_SANS_CHAIN_ID =
    0x91ab3d17e3a50a9d89e63fd30b92be7f5336b03b287bb946787a83a9d62a2766;

_DOMAIN_TYPEHASH_SANS_CHAIN_ID_AND_VERIFYING_CONTRACT

keccak256("EIP712Domain(string name,string version)"). This is only used in _hashTypedDataSansChainIdAndVerifyingContract.

bytes32 internal constant _DOMAIN_TYPEHASH_SANS_CHAIN_ID_AND_VERIFYING_CONTRACT =
    0xb03948446334eb9b2196d5eb166f69b9d49403eb4a12f36de8d3f9f3cb8e15c3;

_DOMAIN_TYPEHASH_SANS_VERIFYING_CONTRACT

keccak256("EIP712Domain(string name,string version,uint256 chainId)"). This is only used in _hashTypedDataSansVerifyingContract.

bytes32 internal constant _DOMAIN_TYPEHASH_SANS_VERIFYING_CONTRACT =
    0xc2f8787176b8ac6bf7215b4adcc1e069bf4ab82d9ab1df05a57a91d425935b6e;

_cachedThis

uint256 private immutable _cachedThis;

_cachedChainId

uint256 private immutable _cachedChainId;

_cachedNameHash

bytes32 private immutable _cachedNameHash;

_cachedVersionHash

bytes32 private immutable _cachedVersionHash;

_cachedDomainSeparator

bytes32 private immutable _cachedDomainSeparator;

Functions

constructor

Cache the hashes for cheaper runtime gas costs. In the case of upgradeable contracts (i.e. proxies), or if the chain id changes due to a hard fork, the domain separator will be seamlessly calculated on-the-fly.

constructor();

_domainNameAndVersion

*Please override this function to return the domain name and version.

function _domainNameAndVersion()
internal
pure
virtual
returns (string memory name, string memory version)
{
name = "Solady";
version = "1";
}

Note: If the returned result may change after the contract has been deployed, you must override _domainNameAndVersionMayChange() to return true.*

function _domainNameAndVersion() internal view virtual returns (string memory name, string memory version);

_domainNameAndVersionMayChange

Returns if _domainNameAndVersion() may change after the contract has been deployed (i.e. after the constructor). Default: false.

function _domainNameAndVersionMayChange() internal pure virtual returns (bool result);

_domainSeparator

Returns the EIP-712 domain separator.

function _domainSeparator() internal view virtual returns (bytes32 separator);

_hashTypedData

*Returns the hash of the fully encoded EIP-712 message for this domain, given structHash, as defined in https://eips.ethereum.org/EIPS/eip-712#definition-of-hashstruct. The hash can be used together with ECDSA-recover to obtain the signer of a message:

bytes32 digest = _hashTypedData(keccak256(abi.encode(
keccak256("Mail(address to,string contents)"),
mailTo,
keccak256(bytes(mailContents))
)));
address signer = ECDSA.recover(digest, signature);
```*


```solidity
function _hashTypedData(bytes32 structHash) internal view virtual returns (bytes32 digest);

_hashTypedDataSansChainId

Variant of _hashTypedData that excludes the chain ID. Included for the niche use case of cross-chain workflows.

function _hashTypedDataSansChainId(bytes32 structHash) internal view virtual returns (bytes32 digest);

_hashTypedDataSansChainIdAndVerifyingContract

Variant of _hashTypedData that excludes the chain ID and verifying contract. Included for the niche use case of cross-chain and multi-verifier workflows.

function _hashTypedDataSansChainIdAndVerifyingContract(bytes32 structHash)
    internal
    view
    virtual
    returns (bytes32 digest);

_hashTypedDataSansVerifyingContract

Variant of _hashTypedData that excludes the chain ID and verifying contract. Included for the niche use case of multi-verifier workflows.

function _hashTypedDataSansVerifyingContract(bytes32 structHash) internal view virtual returns (bytes32 digest);

eip712Domain

See: https://eips.ethereum.org/EIPS/eip-5267

function eip712Domain()
    public
    view
    virtual
    returns (
        bytes1 fields,
        string memory name,
        string memory version,
        uint256 chainId,
        address verifyingContract,
        bytes32 salt,
        uint256[] memory extensions
    );

_buildDomainSeparator

Returns the EIP-712 domain separator.

function _buildDomainSeparator() private view returns (bytes32 separator);

_cachedDomainSeparatorInvalidated

Returns if the cached domain separator has been invalidated.

function _cachedDomainSeparatorInvalidated() private view returns (bool result);

SiglessTransactionExecutor

Git Source

Inherits: ISafeTx, SecuredTokenTransfer, Executor, GuardManager

Author: Ultrasound Labs - @ultrasoundlabs This contract merges the "sigless" execution (no signature check) with the full Safe transaction execution logic. It allows you to execute a SafeTx struct directly, skipping signature checks, but still performing all the other steps (gas accounting, payment, etc) as in the original Safe contract. We don't import the Safe contract to save on gas costs.

Safe account has to delegatecall this contract to execute SafeTx with a normal flow except for the signature verification

State Variables

DOMAIN_SEPARATOR_TYPEHASH

bytes32 private constant DOMAIN_SEPARATOR_TYPEHASH = 0x47e79534a245952e8b16893a336b85a3d9ea9fa8c573f3d803afb92a79469218;

SAFE_TX_TYPEHASH

bytes32 private constant SAFE_TX_TYPEHASH = 0xbb8310d486368db6bd6f849402fdd73ad53d316b5a4b2644ad6efe0f941286d8;

__gap

uint256[5] private __gap;

nonce

Tracks the next expected Safe transaction nonce.

uint256 public nonce;

Functions

revertWithError

Function which uses assembly to revert with the passed error message.

Currently it is expected that the error string is at max 5 bytes of length. Ex: "GSXXX"

function revertWithError(bytes5 error) internal pure;

Parameters

execTransaction

Execute a SafeTx without requiring a signature.

This function unpacks the SafeTx struct and executes the transaction using the same logic as the original Safe contract, but skips signature verification. This is useful for trusted modules or scenarios where signature checks are not needed.

function execTransaction(SafeTx calldata safeTx) public returns (bool success);

Parameters

Returns

_handlePayment

Handles the payment/refund for a Safe transaction.

*Forked from Gnosis Safe handlePayment. Slither’s arbitrary-send-eth detector reports the receiver.send(payment) call below. In the canonical Safe design this is intentional and safe:

1. The refund occurs after successful execution of the user’s transaction.
2. Only the entity footing the gas bill (refundReceiver or tx.origin) receives the refund.
3. The 2 300-gas stipend of .send mitigates re-entrancy; reverting on failure matches upstream semantics and prevents silent griefing.*

function _handlePayment(
    uint256 gasUsed,
    uint256 baseGas,
    uint256 gasPrice,
    address gasToken,
    address payable refundReceiver
) private returns (uint256 payment);

Parameters

Returns

encodeTransactionData

Returns the pre-image of the transaction hash (see getTransactionHash).

Forked from Safe.sol

function encodeTransactionData(
    address to,
    uint256 value,
    bytes memory data,
    Enum.Operation operation,
    uint256 safeTxGas,
    uint256 baseGas,
    uint256 gasPrice,
    address gasToken,
    address refundReceiver,
    uint256 _nonce
) internal view returns (bytes memory);

Parameters

Returns

domainSeparator

Returns the EIP-712 domain separator (chainId hard-coded to 1).

Returns the domain separator for this contract, as defined in the EIP-712 standard.

Forked from Safe.sol

function domainSeparator() public view returns (bytes32 separator);

Returns

getChainId

Returns the ID of the chain the contract is currently deployed on.

Forked from Safe.sol

function getChainId() public view returns (uint256);

Returns

Events

ExecutionFailure

Emitted when a delegated Safe transaction reverts.

event ExecutionFailure(bytes32 indexed txHash, uint256 indexed payment);

Parameters

ExecutionSuccess

Emitted when a delegated Safe transaction executes successfully.

event ExecutionSuccess(bytes32 indexed txHash, uint256 indexed payment);

Parameters

ZeroAddress

Git Source

Custom error thrown when a zero address is provided where it is not allowed.

error ZeroAddress();

UnauthorizedCaller

Git Source

Custom error thrown when a caller other than the AllowanceManager attempts to pull funds.

error UnauthorizedCaller();

PullFailure

Git Source

Custom error thrown when the token transfer fails in _pull.

error PullFailure();

ZeroAmount

Git Source

error ZeroAmount();

AllowanceHolder

Git Source

Inherits: IAllowanceHolder, ReentrancyGuard

Author: Ultrasound Labs

CREATE2-deployed helper that can pull tokens from a user based on a single off-chain permit and hand out per-subaccount quotas via AllowanceManager.

Note: security-contact: security@ultrasoundlabs.org

State Variables

_OWNER

Holder of the tokens. Stored as immutable to optimise gas and used to compute the CREATE2 salt.

address private immutable _OWNER;

_TOKEN

ERC-20 token managed by this holder.

address private immutable _TOKEN;

_ALLOWANCE_MANAGER

AllowanceManager authorised to call pull.

address private immutable _ALLOWANCE_MANAGER;

Functions

constructor

Deploys a new holder and immediately seeds the first quota / initial transfer.

constructor(
    address _owner,
    address _token,
    address _allowanceManager,
    address _subaccount,
    uint256 _quotaAmount,
    uint256 _timeframe,
    uint256 _initialFund,
    bytes memory _firstCallData
);

Parameters

pull

Transfers amount of token() from the owner() directly to subaccount.

Can only be called by allowanceManager().

function pull(address subaccount, uint256 amount) external override nonReentrant;

Parameters

owner

Returns the token owner whose funds can be pulled.

function owner() external view override returns (address);

Returns

token

Returns the ERC-20 token managed by this holder.

function token() external view override returns (address);

Returns

allowanceManager

Returns the AllowanceManager that is authorised to call pull.

function allowanceManager() external view override returns (address);

Returns

_executeFirstCall

Executes the optional first call on the Safe proxy and returns whether it succeeded.

function _executeFirstCall(address subaccount, bytes memory firstCallData) internal returns (bool innerOk);

Parameters

Returns

_pull

Internal helper that attempts to transfer amount of _TOKEN from _OWNER to subaccount.

*Slither flags _token.transferFrom(_OWNER, subaccount, amount) as an "arbitrary-from" transfer (detector slug: arbitrary-send-erc20). In the context of AllowanceHolder this pattern is expected and safe under the following assumptions:

1. _OWNER is an immutable variable that is set exactly once at construction time and never changes afterwards.
2. Only the associated AllowanceManager contract can call pull, which in turn guarantees that internal accounting (spend quotas, non-reentrancy, etc.) is satisfied before any transfer is attempted.
3. The owner explicitly pre-approved this contract (or granted a Permit2 allowance) during the bootstrap phase, so no third party can trigger an unexpected token movement. Because of these guard-rails the transfer cannot be abused to drain tokens from arbitrary wallets, therefore we silence this specific Slither warning for the remainder of the function.*

Prefers an ERC-20 allowance path; falls back to Permit2 allowance. Does not revert – propagates failures as the returned boolean so the caller can decide whether to emit best-effort events or revert.

function _pull(address subaccount, uint256 amount) internal returns (bool ok);

Parameters

Returns

Events

Pulled

Emitted when tokens are successfully pulled from the owner to a subaccount.

event Pulled(address indexed subaccount, uint256 indexed amount);

Parameters

InitialFundFailed

Emitted when the initial funding transfer during construction fails.

event InitialFundFailed(address indexed subaccount, uint256 indexed amount);

Parameters

FirstCallFailed

Emitted when the first arbitrary call during construction reverts.

event FirstCallFailed(address indexed subaccount);

Parameters

AllowanceManager

Git Source

Inherits: EIP712x, IAllowanceManager, ReentrancyGuard

Author: Ultrasound Labs

Manages time-boxed token allowances that can be pulled by subaccounts.

*Each allowance is namespaced by (owner, subaccount, token) and protected from cross-chain replay via the EIP-712x domain separator (chainId hard-fixed to 1). The manager supports two transfer back-ends:

1. A freshly deployed AllowanceHolder (preferred – no approvals necessary after the initial permit)
2. Fallback to a direct ERC-20 allowance or Permit2 allowance given to this contract*

Note: security-contact: security@ultrasoundlabs.org

State Variables

_ALLOWANCE_REQUEST_BATCH_TYPEHASH

Private constant used internally for EIP-712 struct hashing.

bytes32 private constant _ALLOWANCE_REQUEST_BATCH_TYPEHASH = keccak256(
    "AllowanceRequestBatch(AllowanceRequest[] requests,uint256[] chainIds)AllowanceRequest(address subaccount,address token,uint256 amount,uint256 timeframe,uint256 nonce)"
);

_ALLOWANCE_REQUEST_TYPEHASH

Private constant used internally for EIP-712 struct hashing.

bytes32 private constant _ALLOWANCE_REQUEST_TYPEHASH =
    keccak256("AllowanceRequest(address subaccount,address token,uint256 amount,uint256 timeframe,uint256 nonce)");

_PERMIT2

Address of the Permit2 contract used as a back-up transfer mechanism.

address private immutable _PERMIT2;

_factory

Address of the canonical SubaccountFactory allowed to pre-commit holder addresses (set at deploy time or lazily on the first commit if zero).

address private _factory;

_allowances

mapping(address => mapping(address => mapping(address => Allowance))) internal _allowances;

allowanceNonces

Per-(owner,subaccount,token) nonce incremented every time an allowance is (re-)set.

mapping(address => mapping(address => mapping(address => uint256))) public allowanceNonces;

_holderFor

mapping(address => mapping(address => address)) private _holderFor;

_committedHolder

mapping(address => mapping(address => address)) private _committedHolder;

_allowedHolder

Addresses pre-authorised by the canonical factory to call bootstrapAllowance during their constructor. The factory MUST set the flag before deploying the holder via CREATE2 so that the constructor call can pass the check below.

mapping(address => bool) private _allowedHolder;

Functions

constructor

Initializes the AllowanceManager with the Permit2 contract address and the SubaccountFactory.

constructor(address _permit2, address factoryAddr);

Parameters

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

commitHolder

Commits the expected AllowanceHolder address for a given (owner, token) pair.

Must be called once before the first bootstrapAllowance. Only allowed while no canonical holder has been observed yet.

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

Parameters

registerHolder

Registers an additional holder for an (owner, token) pair after the canonical one has already been observed. Must be called by the canonical factory before deploying the new holder so that its constructor can call bootstrapAllowance successfully.

function registerHolder(address holder) external;

Parameters

holderAddress

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

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

Parameters

Returns

factory

Returns the canonical factory address permitted to commit holders.

function factory() external view returns (address factoryAddress);

Returns

permit2

The Permit2 contract address

function permit2() external view returns (address);

Returns

allowances

Mapping to track allowances for subaccounts.

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

Parameters

Returns

allowanceRequestBatchTypehash

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

function allowanceRequestBatchTypehash() external pure returns (bytes32);

Returns

allowanceRequestTypehash

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

function allowanceRequestTypehash() external pure returns (bytes32);

Returns

setAllowances

Sets allowances for a batch of subaccounts

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

Parameters

spendAllowance

Spends an allowance for the caller

function spendAllowance(address owner, address token, uint256 amount) public nonReentrant;

Parameters

hashAllowanceRequestBatch

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

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

Parameters

Returns

_transferFromOwner

Transfers an allowance from the owner to the subaccount.

*Slither raises an arbitrary-send-erc20 finding for the safeTransferFrom(owner, subaccount, amount) call inside this helper. The warning is a false positive in our threat model because:

1. The function is internal and only reached via spendAllowance, after* the allowance window and per-subaccount quota checks have passed.
2. Success still depends on the owner having granted an explicit ERC-20 allowance or Permit2 allowance to this contract. Without such opt-in the transfer will revert.
3. The semantics mirror the well-audited Gnosis Safe flow (AllowanceHolder pull, fallback to safeTransferFrom). For these reasons the transfer cannot be exploited to steal funds from arbitrary users, therefore we silence the detector for the body of the function.*

function _transferFromOwner(address owner, address subaccount, address token, uint256 amount) internal;

Parameters

_predictHolderAddress

Fetches the cached canonical AllowanceHolder for an (owner, token) pair if it has been observed via bootstrapAllowance.

function _predictHolderAddress(address owner, address token) internal view returns (address holder);

Parameters

Returns

_domainNameAndVersion

Returns the EIP-712 domain name and version used by this contract (chainId is hard-wired to 1 in the parent).

*Please override this function to return the domain name and version.

function _domainNameAndVersion()
internal
pure
virtual
returns (string memory name, string memory version)
{
name = "Solady";
version = "1";
}

Note: If the returned result may change after the contract has been deployed, you must override _domainNameAndVersionMayChange() to return true.*

function _domainNameAndVersion() internal pure override returns (string memory name, string memory version);

Returns

Events

HolderPullFailed

Emitted when an attempt to pull funds via AllowanceHolder fails and the flow falls back to the approval path.

event HolderPullFailed(address indexed holder, address indexed subaccount, uint256 indexed amount);

Parameters

Errors

InvalidNonce

error InvalidNonce();

HolderOwnerMismatch

error HolderOwnerMismatch();

HolderTokenMismatch

error HolderTokenMismatch();

HolderManagerMismatch

error HolderManagerMismatch();

HolderMismatch

error HolderMismatch();

AlreadyInitialised

error AlreadyInitialised();

ZeroAmount

error ZeroAmount();

HolderNotCommitted

error HolderNotCommitted();

HolderCommitMismatch

error HolderCommitMismatch();

HolderAlreadyCommitted

error HolderAlreadyCommitted();

UnauthorizedCaller

error UnauthorizedCaller();

ISafe

Git Source

Author: Safe

Minimal subset of the Safe contract needed for signature verification.

Functions

checkSignatures

Verifies the given signatures for dataHash.

function checkSignatures(bytes32 dataHash, bytes memory data, bytes memory signatures) external view;

Parameters

MultiChainSignaturesModule

Git Source

Inherits: ISafeTx

Author: Ultrasound Labs

Safe module that allows the same batched signature to be replayed across multiple chains; only the transactions whose chainIds[i] match block.chainid are executed.

Note: security-contact: security@ultrasoundlabs.org

State Variables

VERSION

Human-readable contract version (kept for backwards compatibility with Safe tooling).

string public constant VERSION = "1.4.1-MCSM";

DOMAIN_SEPARATOR_TYPEHASH

bytes32 private constant DOMAIN_SEPARATOR_TYPEHASH =
    keccak256("EIP712Domain(uint256 chainId,address verifyingContract)");

SAFE_TX_BATCH_TYPEHASH

bytes32 private constant SAFE_TX_BATCH_TYPEHASH = keccak256(
    "SafeTxBatch(address subaccount,SafeTx[] safeTxs,uint256[] chainIds)SafeTx(address to,uint256 value,bytes data,uint8 operation,uint256 safeTxGas,uint256 baseGas,uint256 gasPrice,address gasToken,address refundReceiver,uint256 nonce)"
);

SAFE_TX_TYPEHASH

bytes32 private constant SAFE_TX_TYPEHASH = keccak256(
    "SafeTx(address to,uint256 value,bytes data,uint8 operation,uint256 safeTxGas,uint256 baseGas,uint256 gasPrice,address gasToken,address refundReceiver,uint256 nonce)"
);

SIGLESS_TRANSACTION_EXECUTOR

The address of the SiglessTransactionExecutor library used for delegate-calls.

address public immutable SIGLESS_TRANSACTION_EXECUTOR;

Functions

constructor

Constructs the module.

constructor(address _siglessTransactionExecutor);

Parameters

execTransactionBatch

Executes the subset of safeTxBatch targeted to the current chain.

function execTransactionBatch(address account, SafeTxBatch calldata safeTxBatch, bytes calldata signatures)
    public
    returns (bool success);

Parameters

Returns

encodeTransactionBatchData

Encodes the SafeTxBatch into the pre-image for signature verification following the same structure hashing rules as Safe.

function encodeTransactionBatchData(SafeTxBatch calldata safeTxBatch) public view returns (bytes memory);

Parameters

Returns

domainSeparator

Returns the domain separator used for batch hashing (chainId hard-coded to 1).

function domainSeparator() public view returns (bytes32 separator);

Returns

Events

SafeTxFailed

Emitted when a transaction in the batch reverts on the current chain.

event SafeTxFailed(address indexed safe, uint256 indexed index);

Parameters

Errors

MismatchedSubaccount

Custom errors

error MismatchedSubaccount();

Structs

SafeTxBatch

struct SafeTxBatch {
    address subaccount;
    SafeTx[] safeTxs;
    uint256[] chainIds;
}

OpenSubaccounts

Git Source

Inherits: MultiChainSignaturesModule, SubaccountFactory, AllowanceManager

Author: Ultrasound Labs

Top-level contract that bundles the Subaccount factory, Multi-Chain Signature module and Allowance Manager into a single deployment for convenience.

Note: security-contact: security@ultrasoundlabs.org

Functions

constructor

Constructs a new OpenSubaccounts instance wiring together the SubaccountFactory, MultiChainSignaturesModule and AllowanceManager modules.

constructor(
    address _siglessTransactionExecutor,
    address _safeSingleton,
    address _safeProxyFactory,
    address _safeModuleSetup,
    address _permit2
)
    MultiChainSignaturesModule(_siglessTransactionExecutor)
    SubaccountFactory(_safeSingleton, _safeProxyFactory, _safeModuleSetup, address(this), address(this))
    AllowanceManager(_permit2, address(this));

Parameters

ISafe

Git Source

Functions

execTransactionFromModule

Allows a Module to execute a Safe transaction without any further confirmations.

function execTransactionFromModule(address to, uint256 value, bytes memory data, uint8 operation)
    external
    returns (bool success);

Parameters

execTransactionFromModuleReturnData

Execute operation (0: Call, 1: DelegateCall) to to with value (Native Token) and return data

function execTransactionFromModuleReturnData(address to, uint256 value, bytes memory data, uint8 operation)
    external
    returns (bool success, bytes memory returnData);

Parameters

Returns

checkSignatures

Checks whether the signature provided is valid for the provided data, hash. Will revert otherwise.

function checkSignatures(bytes32 dataHash, bytes memory data, bytes memory signatures) external view;

Parameters

domainSeparator

Returns the domain separator for this contract, as defined in the EIP-712 standard.

function domainSeparator() external view returns (bytes32);

Returns

getModulesPaginated

Returns array of modules.

function getModulesPaginated(address start, uint256 pageSize)
    external
    view
    returns (address[] memory array, address next);

Parameters

Returns

enableModule

Enables the module module for the Safe.

This can only be done via a Safe transaction.

function enableModule(address module) external;

Parameters

getThreshold

Returns the number of required confirmations for a Safe transaction aka the threshold.

function getThreshold() external view returns (uint256);

Returns

SafeModuleSetup

Git Source

The Safe setup function accepts to and data parameters for a delegate call during initialization. This contract can be specified as the to with data ABI encoding the enableModules call so that a Safe is created with the specified modules. In particular, this allows a ERC-4337 compatible Safe to be created as part of a ERC-4337 user operation with the Safe4337Module enabled right away.

Note: security-contact: bounty@safe.global

Functions

enableModules

Enable the specified Safe modules.

This call will only work if used from a Safe via delegatecall. It is intended to be used as part of the Safe setup, allowing Safes to be created with an initial set of enabled modules.

function enableModules(address[] calldata modules) external;

Parameters

SubaccountAddressMismatch

Git Source

error SubaccountAddressMismatch();

HolderAddressMismatch

Git Source

error HolderAddressMismatch();

AllowanceManagerRegistrationFailed

Git Source

error AllowanceManagerRegistrationFailed();

SubaccountFactory

Git Source

Inherits: ReentrancyGuard

Author: Ultrasound Labs

Deploys deterministic Safe-based subaccounts and their AllowanceHolders, and wires them up for multi-chain use.

Note: security-contact: security@ultrasoundlabs.org

State Variables

SAFE_SINGLETON

Canonical Safe singleton (implementation) used for new subaccounts.

address public immutable SAFE_SINGLETON;

SAFE_PROXY_FACTORY

Factory for deploying Safe proxies.

address public immutable SAFE_PROXY_FACTORY;

SAFE_MODULE_SETUP

Helper contract for enabling modules during Safe setup.

address public immutable SAFE_MODULE_SETUP;

MULTICHAIN_SIGNATURES_MODULE

Module providing multi-chain batched signatures.

address public immutable MULTICHAIN_SIGNATURES_MODULE;

ALLOWANCE_MANAGER

Address of the AllowanceManager used by holders.

address public immutable ALLOWANCE_MANAGER;

_enableModulesCalldata

Pre-computed calldata for enabling the MultiChainSignaturesModule via the helper in the Safe setup. This is computed once in the constructor to avoid rebuilding the dynamic array on every subaccount creation.

bytes private _enableModulesCalldata;

isDeployedSubaccount

Records whether a given subaccount proxy has already been deployed.

Keyed by subaccount address.

mapping(address => bool) public isDeployedSubaccount;

isDeployedAllowanceHolder

Records whether the AllowanceHolder for (owner,token) has been deployed.

Keyed by AllowanceHolder address.

mapping(address => bool) public isDeployedAllowanceHolder;

Functions

constructor

Initializes the factory with required contract addresses.

constructor(
    address _safeSingleton,
    address _safeProxyFactory,
    address _safeModuleSetup,
    address _multichainSignaturesModule,
    address _allowanceManager
);

Parameters

createAllowanceHolder

Ensures the AllowanceHolder for (owner, token) exists and has allowance via Permit2.

Deploys the holder deterministically via CREATE2 if not yet deployed, immediately executes permit, and optionally pushes initial quota/fund/first call.

function createAllowanceHolder(
    address owner,
    address token,
    address subaccount,
    uint256 quotaAmount,
    uint256 quotaTimeframe,
    uint256 initialFund,
    bytes calldata firstCallData,
    uint256 permitDeadline,
    uint8 v,
    bytes32 r,
    bytes32 s
) public nonReentrant returns (address holder);

Parameters

Returns

createSubaccount

Deploys a new Safe-based subaccount for owner under appDomain.

function createSubaccount(address owner, string calldata appDomain, uint32 accountIndex)
    public
    returns (address subaccount);

Parameters

Returns

generateSubaccountAddress

Predicts the deterministic address of a subaccount without deploying it.

function generateSubaccountAddress(address owner, string calldata appDomain, uint32 accountIndex)
    public
    view
    returns (address subaccount, bool isDeployed);

Parameters

Returns

generateAllowanceHolderAddress

Predicts the AllowanceHolder address for a given (owner, token) pair.

function generateAllowanceHolderAddress(
    address owner,
    address token,
    address subaccount,
    uint256 quotaAmount,
    uint256 timeframe,
    uint256 initialFund,
    bytes memory firstCallData
) public view returns (address holder, bool isDeployed);

Parameters

Returns

_executePermit

Executes an unlimited permit using native ERC-2612 if available, otherwise falls back to Uniswap Permit2.

Uses SafeTransferLib.permit2, which first attempts token.permit and gracefully falls back to Permit2 if the token does not support ERC-2612 (or the call fails).

function _executePermit(address owner, address token, address spender, uint256 deadline, uint8 v, bytes32 r, bytes32 s)
    internal;

Parameters

_deployAllowanceHolder

Performs the deterministic deployment of the AllowanceHolder using CREATE2.

function _deployAllowanceHolder(
    address owner,
    address token,
    address subaccount,
    uint256 quotaAmount,
    uint256 quotaTimeframe,
    uint256 initialFund,
    bytes calldata firstCallData,
    address predictedHolder
) internal returns (address holder);

Parameters

Returns

_constructInitializer

Constructs the initializer data for Safe setup.

This prepares the calldata for Safe.setup, setting the owner, threshold, and enabling the module.

function _constructInitializer(address owner) internal view returns (bytes memory);

Parameters

Returns

_generateSaltNonce

Converts an app domain string and account index to a salt nonce.

Uses NameCoder to encode and namehash the domain.

function _generateSaltNonce(string calldata appDomain, uint32 accountIndex) internal pure returns (uint256);

Parameters

Returns

_salt

Computes the salt used for CREATE2 deployments.

function _salt(
    address owner,
    address token,
    address manager,
    address subaccount,
    uint256 amount,
    uint256 timeframe,
    uint256 initialFund,
    bytes32 firstCallHash
) internal pure returns (bytes32);

Parameters

Returns

_creationCode

Builds the creation bytecode for the AllowanceHolder constructor params.

function _creationCode(
    address owner,
    address token,
    address manager,
    address subaccount,
    uint256 amount,
    uint256 timeframe,
    uint256 initialFund,
    bytes memory firstCallData
) internal pure returns (bytes memory);

Parameters

Returns

_computeAddress

Computes the deterministic contract address as in EIP-1014.

function _computeAddress(
    address deployer,
    address owner,
    address token,
    address manager,
    address subaccount,
    uint256 amount,
    uint256 timeframe,
    uint256 initialFund,
    bytes memory firstCallData
) internal pure returns (address);

Parameters

Returns

_ownersArray

Helper to create a single-element owners array in memory.

Used internally to format the input for Safe.setup.

function _ownersArray(address owner) private pure returns (address[] memory owners);

Parameters

Returns

Events

SubaccountCreated

Emitted after a successful subaccount deployment.

event SubaccountCreated(
    address indexed subaccount, address indexed owner, string indexed appDomain, uint32 accountIndex
);

Parameters

AllowanceHolderCreated

Emitted when the canonical AllowanceHolder for (owner,token) has been deployed.

event AllowanceHolderCreated(address indexed holder, address indexed owner, address indexed token);

Parameters