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

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

Original ERC · ← ERCs