ERC-8017 Payout Race Payment Bucket (Payout Race)
Draft · Vaults & DeFi · created 2025-08-31
Defines a first-come-first-served payment structure where the entire single asset held by the contract is handed over as-is to whichever caller pays a fixed amount first.
Why it is needed
Protocols often need to convert steady cash flows such as fees or revenue into another asset. Common cases include token buybacks, building up reserve assets, funding incentive budgets, and vault rebalancing. Using an AMM for this makes the outcome depend on external pool liquidity, slippage, and fees, and the configuration has to be readjusted every time pool conditions change. Running continuous on-chain auctions is operationally complex and expensive in gas. ERC-8017 solves this with a small, easily auditable contract that presents a deterministic structure: pay a fixed amount and receive the entire asset accumulated in the bucket on a first-come-first-served basis.
What to implement
function payoutAsset() external view returns (address);: Returns the address of the payout asset leaving the bucket. If address(0), it is ETH.function desiredAsset() external view returns (address);: Returns the address of the payment asset the buyer must pay. If address(0), it is ETH.function requiredPayment() external view returns (uint256);: Returns the fixed payment amount that must be paid to win the race.function paymentSink() external view returns (address);: Returns the destination address to which the buyer's payment is sent.function purchase(address to) external payable returns (uint256 dispensed);: Pays the fixed payment amount and receives the entire payout asset in the bucket, sent to `to`.function setRequiredPayment(uint256 amount) external;: The admin changes the fixed payment amount.function setPaymentSink(address sink) external;: The admin changes the payment recipient.event Purchased(address indexed buyer, address indexed to, uint256 dispensed, uint256 paid);: Emitted when a purchase succeeds and the payout asset is transferred.event PaymentConfigUpdated(address desiredAsset, uint256 requiredPayment, address sink);: Emitted when the payment configuration (payment asset, payment amount, recipient) changes.
In depth
First-come-first-served full payout method
When purchase is called, the contract fixes the current balance of payoutAsset (address(this).balance if payoutAsset is address(0), otherwise balanceOf) as the payout amount at function entry, before making any external call. This entire amount must be sent to `to` in a single call, and the call must revert if the amount is 0. In other words, it is an all-or-nothing method that transfers the entire asset accumulated in the bucket without splitting it.
Asset pair and immutability
payoutAsset and desiredAsset cannot both be address(0) at the same time. In other words, a structure where ETH buys ETH is prohibited. Neither asset must ever change after initialization, and the contract must not expose a setter that can change them. For each asset, address(0) means ETH, otherwise it means the corresponding ERC-20 token.
Payment collection rules
The buyer must pay an amount exactly equal to requiredPayment(). If desiredAsset is address(0) (ETH), msg.value must equal requiredPayment, and that ETH is forwarded to paymentSink(). If desiredAsset is ERC-20, msg.value must be 0, and the contract receives payment by calling transferFrom(msg.sender, paymentSink(), requiredPayment()) on desiredAsset.
Admin configuration and events
setRequiredPayment and setPaymentSink must only be callable by an authorized role, and must emit a PaymentConfigUpdated event whenever a value changes. The specification does not define the access control method, and recommends EIP-173-style ownership or a role-based pattern. Some deployments may renounce ownership or restrict roles for policy or regulatory reasons.
Optional extensions: permit and rescue
The contract may additionally provide purchaseWithPermit, which accepts an EIP-2612 permit signature to complete approval and payment in the same transaction. In this case, desiredAsset must be ERC-20, and the call must revert if desiredAsset does not support EIP-2612 or if the allowance is insufficient after permit. It may also include an admin-only rescue function to recover assets other than payoutAsset (ERC-20 or ETH sent in unintentionally); this function must not be able to move payoutAsset and must emit a Rescued event.
Parameter setting and degenerate cases
This structure works best when value accumulates steadily. If a large amount arrives at once, it can far exceed the required payment amount, letting the excess leak straight to the first caller. If the payout asset's value rises, purchases stop; if it falls, purchases may happen too often and cause value loss. Lowering requiredPayment lets searchers cheaply take assets that have already accumulated past the new threshold at the time of the change, while raising it risks bankrupting searchers or MEV bots that were earning fees through arbitrage. Mitigations suggested include timelocks, advance notice periods, per-block deposit limits, cooldowns after changes, and TWAP-based adjustments.
Considered alternative: multi-asset sweep
An alternative considered was sweeping multiple allowlisted tokens together in the same way upon a successful purchase, instead of a single payout asset. This ERC reviewed this extension but did not adopt it, narrowing scope to a single-asset bucket.
Proposal status
ERC-8017 is currently in Draft status, a proposal whose specification may still change or be discontinued.
Things to watch out for
- Reentrancy and call ordering: The Checks-Effects-Interactions pattern and reentrancy guards must be used so that no callback can occur between fixing the payout amount, collecting payment, and before payment is received, and completing the payout.
- Recipient constraints: The recipient address `to` must be able to receive the payout asset. ETH payouts require a payable fallback, and ERC-20 payouts require that `to` not be a contract that reverts on transfer.
- Payment recipient constraints: paymentSink must be able to receive the payment asset. If ETH, it must be payable; if ERC-20, it must not reject amounts arriving via transferFrom.
- Unintended transfers: ETH or ERC-20 sent directly to the contract is included as-is in the next payout. Operators must account for this during integration, and an admin-only rescue function that recovers assets other than payoutAsset can mitigate mistakes.
- Admin change protection: Setters that can change requiredPayment or paymentSink must be protected by governance. Common mitigations include timelocks, changes with advance notice periods, and immutabilizing parameters that must never change.