ERC-8187: Token Puller

Interface for permissioned, on-demand token pulls with custom sourcing logic, permit support, and allowance delegation

Abstract

This ERC proposes a standardized interface for “Puller” contracts that enable approved spenders to initiate token transfers from an owner’s account without requiring the owner to maintain liquid balances. The Puller handles custom logic for sourcing tokens (e.g., withdrawing or borrowing from lending protocols, liquidating positions, or other operations) and executes the transfer to a specified destination.

The interface supports:

• On-chain approvals with limits
• Off-chain EIP-712 signed permits (with ERC-6492 universal signature validation)
• Atomic permit + pull operations
• Allowance delegation/transfer between spenders
• Renunciation of allowances

This enables use cases such as recurring payments, subscriptions, automated settlements, guardian-managed limits, and credit-card-like spending controls in DeFi and payment applications, while improving security and yield optimization.

Motivation

Current token approval standards (ERC-20 approve/transferFrom, ERC-2612 permits) require owners to hold liquid balances and often involve multiple transactions or direct balance pulls. This creates friction and risks:

• Owners forgo yield from invested positions (vaults or other DeFi protocols)
• Atomization of funds in multiple accounts linked to different spending mechanisms (like crypto credit cards/neo banks)
• Large liquid balances in hot wallets increase security risks
• Recurring or delegated payments require frequent owner interaction
• No standardized way for one spender to delegate portions of their allowance (e.g., budget enforcers or guardians)

The Token Puller Interface addresses these by introducing an intermediary Puller contract that:

• Manages approvals and limits
• Executes custom sourcing logic during pulls
• Supports signature-based approvals compatible with externally owned accounts (EOAs), smart accounts, and pre-deploy contracts
• Allows spenders to transfer/renounce portions of their allowances

The core motivation behind this ERC is to cleanly decouple spending logic from asset management strategies. By introducing a Puller contract (or, in the smart-account case, the account itself), the act of sourcing tokens — whether from a lending position, a vault, a swap, or simply an internal balance — becomes an implementation detail hidden from the spender. The spender only requests a pull for a certain amount and token; it never needs to know or interact with how those tokens are actually obtained. This atomic sourcing + transfer pattern reduces complexity on the payment or spending side while letting users keep their funds invested until the moment they are needed.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Definitions

The following terms are used with these specific meanings in this specification:

• Puller — The smart contract that implements the IPuller interface. It acts as the intermediary responsible for:

  • Managing pull allowances granted by owners to spenders,
  • Validating pull requests,
  • Executing implementation-specific sourcing logic to obtain tokens (e.g. withdrawing from a lending protocol, redeeming from a vault, swapping, etc.),
  • Transferring the obtained tokens to the requested destination,
  • Supporting off-chain signed permits and allowance delegation.

• Token — An ERC-20 compliant fungible token contract whose tokens can be pulled through this interface. The Puller MUST be able to ultimately transfer such tokens to the destination address after sourcing them.

• Owner — The address (EOA or smart contract account) that:

  • Owns or has control over the tokens (directly or indirectly through pre-approvals to the Puller or other protocols),
  • Grants pull allowances to spenders (via approvePull or permitPull),
  • Is the entity from which tokens are sourced during a pullFrom or pullFromWithPermit call.

• Spender — An address (EOA, smart contract, or relayer) that has been granted a pull allowance by an owner (via on-chain approval or signed permit) and is authorized to call pullFrom, pullFromWithPermit, or transferPullAllowance to initiate token movements or delegate portions of its allowance.

Additional terms that appear frequently and benefit from clear definition:

• Pull Allowance (or simply Allowance) — The maximum cumulative amount of a specific token that a given spender is permitted to pull from a given owner via the Puller, as tracked by pullAllowance(token, owner, spender). This value can be finite or infinite (type(uint256).max).

• Sourcing Logic — The implementation-specific mechanism executed by the Puller during a successful pullFrom or pullFromWithPermit call to make tokens available for transfer. Examples include withdrawing from lending protocols, redeeming vault shares, unwrapping tokens, or performing swaps. The exact logic is outside the scope of this ERC and is defined by each Puller implementation.

• Permit — An off-chain EIP-712 signed message (following the PullPermit struct) that authorizes setting or updating a pull allowance without requiring an on-chain approvePull transaction from the owner.

Methods

approvePull

function approvePull(address token, address spender, uint256 limit) external

Sets or updates the pull allowance of spender for token from msg.sender (the owner).

• MUST revert if called by any address other than the owner.
• Setting limit to 0 revokes the spender’s permission to pull that token.
• MUST overwrite any previous allowance for (token, owner, spender) with the new limit.
• MUST emit the PullApproval event.

pullFrom

function pullFrom(address token, address owner, address to, uint256 amount) external

Pulls amount of token from owner and transfers it to to, after executing the Puller’s implementation-specific sourcing logic.

• MUST revert unless msg.sender has sufficient allowance: pullAllowance(token, owner, msg.sender) >= amount.
• When msg.sender == owner, the Puller MAY ignore the allowance check. In that case, the Puller just abstracts away the sourcing logic.
• If the current allowance is not type(uint256).max, MUST decrease the allowance by amount.
• MAY skip decreasing the allowance when it is type(uint256).max (infinite approval).
• SHOULD execute the Puller’s custom sourcing logic to obtain the tokens (implementation-defined).
• MUST transfer exactly amount of token to to.
• MUST revert if sourcing fails, allowance is insufficient, caller is unauthorized, or the transfer reverts.
• MUST emit the TokensPulled event on success.

transferPullAllowance

function transferPullAllowance(address token, address owner, address toSpender, uint256 amount) external

Transfers amount of pull allowance from msg.sender (the current spender) to toSpender for the (token, owner) pair.

• MUST revert unless pullAllowance(token, owner, msg.sender) >= amount.
• Special case — infinite allowance transfer:
  • If amount == type(uint256).max and current allowance == type(uint256).max:
    • MUST set msg.sender’s allowance to 0
    • MUST set toSpender’s allowance to type(uint256).max
• Otherwise:
  • MUST decrease msg.sender’s allowance by amount (unless infinite)
  • MUST increase toSpender’s allowance by amount (unless toSpender == address(0))
• SHOULD allow toSpender == address(0) as a mechanism to renounce allowance (decrease only, no increase).
• MUST revert if toSpender == msg.sender (self-transfer is a no-op and should be prevented).
• MUST emit the TransferPullAllowance event on success.

pullAllowance

function pullAllowance(address token, address owner, address spender) external view returns (uint256)

Returns the units of token that spender is allowed to pull from owner.

maxPullable

function maxPullable(address token, address owner, uint256 upTo) external view returns (uint256)

Returns the max amount that can be pulled of a given token from a given owner. The upTo parameter allows early termination if that amount is reached.

• The returned value MUST be between 0 and upTo.
• The maximum amount that can be pulled from a given owner by a given spender can be computed with maxPullable(token, owner, pullAllowance(token, owner, spender)).

permitPull

function permitPull(
    address token,
    address owner,
    address spender,
    uint256 limit,
    uint256 deadline,
    bytes calldata signature
) external

Approves or updates a pull allowance using an off-chain EIP-712 signature.

• The signature MUST be over the PullPermit struct:
  • token, owner, spender, limit, nonce = nonces(owner), deadline
• PullPermit typehash:

    keccak256("PullPermit(address token,address owner,address spender,uint256 limit,uint256 nonce,uint256 deadline)")
  

• Digest computation:

    keccak256(abi.encodePacked(
        hex"1901",
        DOMAIN_SEPARATOR,
        keccak256(abi.encode(TYPEHASH, token, owner, spender, limit, nonces(owner), deadline))
    ))
  

  where DOMAIN_SEPARATOR is defined according to EIP-712. The DOMAIN_SEPARATOR should be unique to the contract and chain to prevent replay attacks from other domains, and satisfy the requirements of EIP-712, but is otherwise unconstrained.

• SHOULD validate the signature following ERC-6492 rules (EOA via ecrecover, ERC-1271 contracts, pre-deploy via magic suffix).
• MUST revert if block.timestamp > deadline, signature is invalid, or nonce does not match.
• On success:
  • MUST increment nonces(owner)
  • MUST set pullAllowance(token, owner, spender) to limit (overwriting previous value)
  • MUST emit PullApproval(token, owner, spender, limit)
• MAY be called by anyone (e.g., spender, relayer).

pullFromWithPermit

function pullFromWithPermit(
    address token,
    address owner,
    address to,
    uint256 amount,
    uint256 deadline,
    bytes calldata signature
) external

Atomically applies a permit (with limit == amount) and executes a pull in a single transaction.

• The signature MUST correspond to a PullPermit where limit == amount and spender == msg.sender.
• SHOULD call permitPull(token, owner, msg.sender, amount, deadline, signature), but it SHOULD NOT revert if this call fails, to avoid a front-run DoS attack.
• On successful permit:
  • MUST set allowance to amount
  • MUST immediately call the equivalent of pullFrom(token, owner, to, amount)
• If the permit was successfully applied, MUST emit PullApproval followed by TokensPulled; otherwise MUST emit only TokensPulled

Other methods

Implementations SHOULD expose the domain via ERC-5267.

Implementations MUST expose nonces(owner) as described in ERC-2612.

Events

PullApproval

event PullApproval(address indexed token, address indexed owner, address indexed spender, uint256 limit)

Emitted when an owner approves or updates a spender’s pull allowance for a given token.

• MUST be emitted whenever approvePull is successfully called.
• MUST be emitted whenever permitPull successfully sets or overwrites an allowance.
• MUST NOT be emitted on allowance transfers via transferPullAllowance.

TokensPulled

event TokensPulled(address indexed token, address indexed owner, address indexed spender, address to, uint256 amount)

Emitted when tokens are successfully pulled from an owner and transferred to the destination.

• MUST be emitted on every successful pullFrom or pullFromWithPermit call.
• The amount parameter MUST reflect the exact amount transferred to to.

TransferPullAllowance

event TransferPullAllowance(address indexed token, address indexed owner, address indexed fromSpender, address toSpender, uint256 amount)

Emitted when a spender transfers part or all of their pull allowance to another spender (or renounces it by transferring to address(0)).

• MUST be emitted on every successful transferPullAllowance call.
• When renouncing (toSpender == address(0)), the event MUST still be emitted with toSpender = address(0).

Interface

// SPDX-License-Identifier: CC0-1.0
pragma solidity ^0.8.0;

interface IPuller {
    // Events
    event PullApproval(address indexed token, address indexed owner, address indexed spender, uint256 limit);
    event TokensPulled(address indexed token, address indexed owner, address indexed spender, address to, uint256 amount);
    event TransferPullAllowance(address indexed token, address indexed owner, address indexed fromSpender, address toSpender, uint256 amount);

    // Core functions
    function approvePull(address token, address spender, uint256 limit) external;
    function pullFrom(address token, address owner, address to, uint256 amount) external;
    function pullAllowance(address token, address owner, address spender) external view returns (uint256);
    function maxPullable(address token, address owner, uint256 upTo) external view returns (uint256);

    // Allowance delegation
    function transferPullAllowance(address token, address owner, address toSpender, uint256 amount) external;

    function permitPull(
        address token,
        address owner,
        address spender,
        uint256 limit,
        uint256 deadline,
        bytes calldata signature
    ) external;

    function pullFromWithPermit(
        address token,
        address owner,
        address to,
        uint256 amount,
        uint256 deadline,
        bytes calldata signature
    ) external;
}

Rationale

Gasless approvals via signed permits and the ability to transfer allowances between spenders were added specifically to support credit-card-like experiences and delegated spending flows. For example, a user might grant a large or infinite allowance to a trusted “guardian” service that enforces daily/monthly limits and automatically refills sub-allowances for individual spenders (e.g., a payment app or merchant processor). These features make recurring or delegated payments more practical without requiring the owner to sign every transaction or maintain liquid balances.

The interface deliberately mirrors familiar ERC-20 patterns (approve / allowance / transferFrom) and builds on established extensions like ERC-2612 (Permit) to minimize the learning curve and avoid unnecessary naming collisions. Where possible, function names, event structures, and parameter ordering stay close to precedents so developers and tools can adopt the standard quickly.

The maxPullable function provides a standardized way to query available pull capacity (similar to balanceOf for direct holdings or maxWithdraw in ERC-4626), independent of spender allowances. The upTo parameter allows efficient checks in cascaded sourcing implementations without forcing full strategy evaluation every time.

Finally, the design is intentionally compatible with both EOAs and smart accounts, while leaning into the current direction of account abstraction (ERC-4337 and others). A particularly powerful pattern is for a smart account to implement the IPuller interface directly on itself. In that case owner == address(this), the account already controls its own funds (and any pre-approved external positions), and there is no need to grant approvals or trust an external Puller contract. This reduces deployment overhead, eliminates an extra approval step, and allows the pull logic to participate in batched user operations — a natural fit for modular wallets that already expose custom execution and spending-limit interfaces.

Reference Implementation

A reference implementation is provided, with a commented interface and an educational example implementation of a Puller that pulls funds by withdrawing them from a vault.

This example has not been audited and should not be used in production environments.

See contracts

Security Considerations

• External calls during sourcing (e.g. withdrawals, redemptions, swaps) can open reentrancy vectors. Implementations must follow checks-effects-interactions and protect against recursive calls.

• Allowance transfer enables refill patterns (guardian refilling sub-allowances), but a compromised spender can redirect its allowance to arbitrary addresses. The same trade-offs between infinite and finite allowances that apply to ERC-20 also apply here: infinite approvals improve user experience but increase damage potential if the spender is compromised.

• Custom sourcing logic can depend on external protocols that are subject to oracle manipulation, failed withdrawals, slippage, or protocol-specific exploits. Implementations should apply appropriate output guards where the logic allows it.

• Permit signatures depend on correct validation of EIP-712 digests, nonces, deadlines, and ERC-6492 rules (EOA recovery, ERC-1271 contracts, pre-deploy detection). Errors in any of these steps can lead to unauthorized approvals.

• Fee-on-transfer and rebasing tokens may behave unexpectedly during sourcing and transfer. Implementations should test with such tokens and consider before/after balance checks when necessary.

• When the Puller interface is implemented directly on a smart account (owner == address(this)), any bug in the Puller code affects the entire account. Modular designs that isolate the logic are preferable.

Production implementations should be audited with special attention to the sourcing paths, signature validation, and allowance transfer logic.

Copyright

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Guillermo Narvaja (@gnarvaja), "ERC-8187: Token Puller [DRAFT]," Ethereum Improvement Proposals, no. 8187, February 2026. Available: https://eips.ethereum.org/EIPS/eip-8187.