ERC-8187 Token Puller interface (Token Puller)
Draft · Vaults & DeFi · created 2026-02-27
A standard interface that lets an approved spender directly pull tokens when needed, within a set limit, even while funds remain deposited or invested.
Why it is needed
With ERC-20's approve/transferFrom or ERC-2612 permit, the owner's wallet must hold a cash-like balance in advance for a spender to take tokens. This forces owners to leave funds idle in their wallet rather than depositing or investing them, giving up potential yield. Funds also have to be partitioned separately for each payment method, and holding a large balance in a wallet increases hacking risk. For recurring spending such as subscriptions or regular payments, the owner must sign or intervene every time, and there is no standard way for a spender who received an allowance to delegate part of it to another spender.
What to implement
function approvePull(address token, address spender, uint256 limit) external: The owner sets or overwrites the spender's pull allowance for a specific token to limit.function pullFrom(address token, address owner, address to, uint256 amount) external: Sources amount of token from owner within the allowance and transfers it to to.function pullAllowance(address token, address owner, address spender) external view returns (uint256): Queries the amount of token the spender is approved to pull from the owner.function maxPullable(address token, address owner, uint256 upTo) external view returns (uint256): Queries the maximum amount, up to upTo, that can actually be sourced from the owner regardless of the allowance.function transferPullAllowance(address token, address owner, address toSpender, uint256 amount) external: Transfers or returns part of msg.sender's allowance to another toSpender.event PullApproval(address indexed token, address indexed owner, address indexed spender, uint256 limit): Emitted when the allowance is set or updated via approvePull or permitPull.event TokensPulled(address indexed token, address indexed owner, address indexed spender, address to, uint256 amount): Emitted when tokens are successfully transferred via pullFrom or pullFromWithPermit.event TransferPullAllowance(address indexed token, address indexed owner, address indexed fromSpender, address toSpender, uint256 amount): Emitted when an allowance is delegated to or returned by another spender.
In depth
approvePull: setting an on-chain allowance
The owner (msg.sender) sets the spender's pull allowance for a specific token to limit. If called by an address other than the owner it must revert, and setting limit to 0 revokes that spender's authorization. Any existing allowance stored for the (token, owner, spender) combination must be overwritten with the new limit, and a PullApproval event must be emitted on success.
pullFrom: pulling tokens
The core function by which a spender receives amount of token from owner, transferred to to. The caller's allowance must be at least amount, and unless the allowance is infinite (type(uint256).max), it must be decremented by the amount used. The decrement can be skipped if the allowance is infinite. When owner calls directly, the allowance check can be skipped, in which case the Puller merely handles the sourcing logic on the owner's behalf. If sourcing fails, the allowance is insufficient, or the transfer reverts, the entire call must revert, and a TokensPulled event must be emitted on success.
transferPullAllowance: delegating or returning an allowance
Transfers part (amount) of the current spender's (msg.sender) allowance for the (token, owner) combination to another toSpender. If both amount and the current allowance are infinite, msg.sender's allowance is set to 0 and toSpender's allowance is set to infinite. Otherwise, msg.sender's allowance is decreased by amount and toSpender's allowance is increased by the same amount. Specifying toSpender as address(0) returns the allowance by only decreasing it without increasing any other allowance. Transferring to oneself is prohibited, and a TransferPullAllowance event is emitted on success.
Query functions: pullAllowance and maxPullable
pullAllowance(token, owner, spender) is a view function that returns the amount of token that spender can pull from owner. maxPullable(token, owner, upTo) returns the maximum amount that can actually be pulled from owner, where upTo is a parameter that lets the computation stop early once that value is reached. The return value must always be between 0 and upTo, and the maximum amount a specific spender can actually pull can be computed as maxPullable(token, owner, pullAllowance(token, owner, spender)).
permitPull: off-chain signed approval
Without an on-chain transaction from owner, this sets or updates the allowance using an EIP-712 signed PullPermit struct (token, owner, spender, limit, nonce, deadline). The signature must be verified per ERC-6492 rules: ecrecover for EOAs, ERC-1271 for contract wallets, and the magic suffix method for wallets not yet deployed. It must revert if block.timestamp has passed deadline, the signature is invalid, or the nonce does not match. On success, it increments owner's nonce, overwrites the allowance with limit, and emits a PullApproval event. Anyone (including the spender or a relayer) can call this function.
pullFromWithPermit: approval and withdrawal in one step
Using a PullPermit signature where limit equals amount, this atomically handles setting the allowance and pulling tokens in a single transaction. The spender in the signature must equal msg.sender. Internally it behaves equivalently to calling permitPull, but if that call fails, it must not revert the entire transaction. This avoids a front-run denial-of-service attack where someone else submits the permit first and preempts it. If the permit was actually applied, a PullApproval event is emitted followed by a TokensPulled event; if it was not applied, only the TokensPulled event is emitted.
Events and ERC-2612/5267 integration
PullApproval is emitted whenever the allowance is set or updated via approvePull or permitPull, and is not emitted by transferPullAllowance. TokensPulled must be emitted every time a call to pullFrom or pullFromWithPermit succeeds, and amount must exactly equal the amount actually transferred to to. TransferPullAllowance is emitted every time an allowance delegation or return succeeds, and the event must still be emitted even when returning to address(0). Implementations must expose nonces(owner) per ERC-2612, and exposing domain information via ERC-5267 is recommended.
A proposal that has not yet been finalized
This ERC is currently in Draft status, proposed on February 27, 2026, and is still under community discussion and review. The function signatures or detailed rules may change going forward, or discussion may stall without further progress.
Things to watch out for
- Reentrancy risk in the sourcing process: Sourcing logic such as withdrawals, repayments, or swaps may open a reentrancy attack path when calling external contracts. Implementations must follow the checks-effects-interactions pattern and prevent recursive calls.
- Exploit paths opened up by allowance delegation: transferPullAllowance enables a pattern where a guardian tops up a sub-spender's limit, but if the spender account is compromised, the allowance can be transferred to an arbitrary address. As with unlimited approvals in ERC-20, an unlimited allowance improves usability but also increases the scale of damage if compromised.
- Risk of sourcing logic depending on external protocols: External protocols that custom sourcing logic depends on may be exposed to oracle manipulation, withdrawal failures, slippage, or vulnerabilities in the protocol itself. Implementations should apply safeguards on return values where possible.
- Permit signature verification errors: Permit signatures must be fully and correctly verified across the EIP-712 digest, nonce, deadline, and ERC-6492 rules (EOA recovery, ERC-1271 contracts, detection of undeployed wallets). If any one of these steps is wrong, an unauthorized approval could be established.
- Risk of implementing directly on a smart account: If the Puller interface is implemented directly on the smart account itself, operating with owner == address(this), a bug in the Puller code affects the entire account. A modular design that isolates the logic separately is preferable.