Skip to main content

DutchAuctionBurner

The DutchAuctionBurner is a burner for the FeeCollector that sells collected fee tokens into the fee target token through a weekly Dutch auction. Each week, during the FeeCollector's COLLECT epoch, every fee token's balance is staged as a lot. During the following EXCHANGE epoch, the price of each lot decays exponentially from start_total to floor_total, and anyone can buy from it, either directly via take or through an external settlement protocol (such as CoW Protocol) that reaches the burner through registry-managed adapters and ERC-1271 signatures. All proceeds go straight to the FeeCollector.

DutchAuctionBurner.vy

The source code for the DutchAuctionBurner.vy contract can be found on GitHub. The contract is written in Vyper version 0.5.0b1 and compiled with the experimental Venom code generator for the cancun EVM version.

The contract is composed of several modules, all found in the same repository: dutch_auction.vy (auction core), dutch_auction_math.vy (price curve), yearn_auction.vy (Yearn compatibility views), adapters.vy (signature router and executor approvals), and the shared roles.vy, recovery.vy and token.vy utilities.

The contract is deployed on:

{ }Contract ABI▼
[{"name":"ReceiverSet","inputs":[{"name":"receiver","type":"address","indexed":true}],"anonymous":false,"type":"event"},{"name":"EconomicsSet","inputs":[{"name":"want","type":"address","indexed":true},{"name":"start_total","type":"uint256","indexed":false},{"name":"floor_total","type":"uint256","indexed":false},{"name":"step_duration","type":"uint256","indexed":false}],"anonymous":false,"type":"event"},{"name":"Taken","inputs":[{"name":"token","type":"address","indexed":true},{"name":"caller","type":"address","indexed":true},{"name":"receiver","type":"address","indexed":false},{"name":"amount_out","type":"uint256","indexed":false},{"name":"payment","type":"uint256","indexed":false},{"name":"remaining_balance","type":"uint256","indexed":false}],"anonymous":false,"type":"event"},{"name":"LotStaged","inputs":[{"name":"token","type":"address","indexed":true},{"name":"initial_amount","type":"uint256","indexed":false},{"name":"start_total","type":"uint256","indexed":false},{"name":"floor_total","type":"uint256","indexed":false},{"name":"start","type":"uint256","indexed":false},{"name":"end","type":"uint256","indexed":false}],"anonymous":false,"type":"event"},{"name":"Recovered","inputs":[{"name":"token","type":"address","indexed":true},{"name":"amount","type":"uint256","indexed":false}],"anonymous":false,"type":"event"},{"name":"BadFeeCollector","inputs":[],"type":"error"},{"name":"BadTarget","inputs":[],"type":"error"},{"name":"BadExchangeFrame","inputs":[],"type":"error"},{"name":"OnlyFeeCollector","inputs":[],"type":"error"},{"name":"TargetChanged","inputs":[],"type":"error"},{"name":"NotSleepEpoch","inputs":[],"type":"error"},{"name":"BadRoleSource","inputs":[],"type":"error"},{"name":"BadReceiver","inputs":[],"type":"error"},{"name":"StartTotalTooLarge","inputs":[],"type":"error"},{"name":"FloorAboveStart","inputs":[],"type":"error"},{"name":"ZeroFloor","inputs":[],"type":"error"},{"name":"BadWant","inputs":[],"type":"error"},{"name":"BadStartTotal","inputs":[],"type":"error"},{"name":"BadFloor","inputs":[],"type":"error"},{"name":"ZeroStep","inputs":[],"type":"error"},{"name":"StepExceedsAuction","inputs":[],"type":"error"},{"name":"BadAuctionLength","inputs":[],"type":"error"},{"name":"BadRegistry","inputs":[],"type":"error"},{"name":"DivisionByZero","inputs":[],"type":"error"},{"name":"AmountExceedsAvailable","inputs":[],"type":"error"},{"name":"ZeroReceiver","inputs":[],"type":"error"},{"name":"NothingAvailable","inputs":[],"type":"error"},{"name":"Deadline","inputs":[],"type":"error"},{"name":"InsufficientAmount","inputs":[],"type":"error"},{"name":"ExcessivePayment","inputs":[],"type":"error"},{"name":"BadBuyToken","inputs":[],"type":"error"},{"name":"LotInactive","inputs":[],"type":"error"},{"name":"BadSellAmount","inputs":[],"type":"error"},{"name":"BadValidTo","inputs":[],"type":"error"},{"name":"BadBuyAmount","inputs":[],"type":"error"},{"name":"WantNotSellable","inputs":[],"type":"error"},{"name":"OnlyOwner","inputs":[],"type":"error"},{"stateMutability":"view","type":"function","name":"auction_length","inputs":[],"outputs":[{"name":"","type":"uint256"}]},{"stateMutability":"view","type":"function","name":"want","inputs":[],"outputs":[{"name":"","type":"address"}]},{"stateMutability":"view","type":"function","name":"receiver","inputs":[],"outputs":[{"name":"","type":"address"}]},{"stateMutability":"view","type":"function","name":"start_total","inputs":[],"outputs":[{"name":"","type":"uint256"}]},{"stateMutability":"view","type":"function","name":"floor_total","inputs":[],"outputs":[{"name":"","type":"uint256"}]},{"stateMutability":"view","type":"function","name":"step_duration","inputs":[],"outputs":[{"name":"","type":"uint256"}]},{"stateMutability":"view","type":"function","name":"lots","inputs":[{"name":"arg0","type":"address"}],"outputs":[{"name":"","type":"tuple","components":[{"name":"staged_at","type":"uint256"},{"name":"initial_amount","type":"uint256"}]}]},{"stateMutability":"view","type":"function","name":"window","inputs":[{"name":"_token","type":"address"}],"outputs":[{"name":"","type":"uint256"},{"name":"","type":"uint256"}]},{"stateMutability":"view","type":"function","name":"window","inputs":[{"name":"_token","type":"address"},{"name":"_timestamp","type":"uint256"}],"outputs":[{"name":"","type":"uint256"},{"name":"","type":"uint256"}]},{"stateMutability":"view","type":"function","name":"available","inputs":[{"name":"_from","type":"address"}],"outputs":[{"name":"","type":"uint256"}]},{"stateMutability":"view","type":"function","name":"price","inputs":[{"name":"_from","type":"address"}],"outputs":[{"name":"","type":"uint256"}]},{"stateMutability":"view","type":"function","name":"price","inputs":[{"name":"_from","type":"address"},{"name":"_ts","type":"uint256"}],"outputs":[{"name":"","type":"uint256"}]},{"stateMutability":"view","type":"function","name":"getAmountNeeded","inputs":[{"name":"_from","type":"address"}],"outputs":[{"name":"","type":"uint256"}]},{"stateMutability":"view","type":"function","name":"getAmountNeeded","inputs":[{"name":"_from","type":"address"},{"name":"amountToTake","type":"uint256"}],"outputs":[{"name":"","type":"uint256"}]},{"stateMutability":"view","type":"function","name":"getAmountNeeded","inputs":[{"name":"_from","type":"address"},{"name":"amountToTake","type":"uint256"},{"name":"_ts","type":"uint256"}],"outputs":[{"name":"","type":"uint256"}]},{"stateMutability":"nonpayable","type":"function","name":"take","inputs":[{"name":"_from","type":"address"}],"outputs":[{"name":"","type":"uint256"}]},{"stateMutability":"nonpayable","type":"function","name":"take","inputs":[{"name":"_from","type":"address"},{"name":"maxAmount","type":"uint256"}],"outputs":[{"name":"","type":"uint256"}]},{"stateMutability":"nonpayable","type":"function","name":"take","inputs":[{"name":"_from","type":"address"},{"name":"maxAmount","type":"uint256"},{"name":"takerReceiver","type":"address"}],"outputs":[{"name":"","type":"uint256"}]},{"stateMutability":"nonpayable","type":"function","name":"take","inputs":[{"name":"_from","type":"address"},{"name":"maxAmount","type":"uint256"},{"name":"takerReceiver","type":"address"},{"name":"data","type":"bytes"}],"outputs":[{"name":"","type":"uint256"}]},{"stateMutability":"nonpayable","type":"function","name":"take_with_limits","inputs":[{"name":"_from","type":"address"},{"name":"_max_amount","type":"uint256"},{"name":"_min_amount","type":"uint256"},{"name":"_max_payment","type":"uint256"},{"name":"_receiver","type":"address"},{"name":"_deadline","type":"uint256"},{"name":"_data","type":"bytes"}],"outputs":[{"name":"","type":"uint256"},{"name":"","type":"uint256"}]},{"stateMutability":"view","type":"function","name":"check_order","inputs":[{"name":"_sell_token","type":"address"},{"name":"_buy_token","type":"address"},{"name":"_receiver","type":"address"},{"name":"_sell_amount","type":"uint256"},{"name":"_min_buy_amount","type":"uint256"},{"name":"_valid_to","type":"uint256"}],"outputs":[{"name":"","type":"bool"}]},{"stateMutability":"view","type":"function","name":"isActive","inputs":[{"name":"_from","type":"address"}],"outputs":[{"name":"","type":"bool"}]},{"stateMutability":"view","type":"function","name":"auctionLength","inputs":[],"outputs":[{"name":"","type":"uint256"}]},{"stateMutability":"view","type":"function","name":"auctions","inputs":[{"name":"_from","type":"address"}],"outputs":[{"name":"","type":"tuple","components":[{"name":"kicked","type":"uint64"},{"name":"scaler","type":"uint64"},{"name":"initialAvailable","type":"uint128"}]}]},{"stateMutability":"view","type":"function","name":"owner","inputs":[],"outputs":[{"name":"","type":"address"}]},{"stateMutability":"view","type":"function","name":"registry","inputs":[],"outputs":[{"name":"","type":"address"}]},{"stateMutability":"nonpayable","type":"function","name":"sync_executor_approvals","inputs":[{"name":"_executor","type":"address"},{"name":"_tokens","type":"address[]"}],"outputs":[]},{"stateMutability":"view","type":"function","name":"isValidSignature","inputs":[{"name":"_hash","type":"bytes32"},{"name":"_signature","type":"bytes"}],"outputs":[{"name":"","type":"bytes4"}]},{"stateMutability":"nonpayable","type":"function","name":"burn","inputs":[{"name":"_coins","type":"address[]"},{"name":"_receiver","type":"address"}],"outputs":[]},{"stateMutability":"nonpayable","type":"function","name":"resync_target","inputs":[{"name":"_expected_target","type":"address"},{"name":"_start_total","type":"uint256"},{"name":"_floor_total","type":"uint256"},{"name":"_step_duration","type":"uint256"}],"outputs":[]},{"stateMutability":"nonpayable","type":"function","name":"push_target","inputs":[],"outputs":[{"name":"","type":"uint256"}]},{"stateMutability":"nonpayable","type":"function","name":"recover","inputs":[{"name":"_coins","type":"address[]"}],"outputs":[]},{"stateMutability":"view","type":"function","name":"supportsInterface","inputs":[{"name":"_interface_id","type":"bytes4"}],"outputs":[{"name":"","type":"bool"}]},{"stateMutability":"view","type":"function","name":"VERSION","inputs":[],"outputs":[{"name":"","type":"string"}]},{"stateMutability":"view","type":"function","name":"fee_collector","inputs":[],"outputs":[{"name":"","type":"address"}]},{"stateMutability":"nonpayable","type":"constructor","inputs":[{"name":"_fee_collector","type":"address"},{"name":"_start_total","type":"uint256"},{"name":"_floor_total","type":"uint256"},{"name":"_step_duration","type":"uint256"},{"name":"_registry","type":"address"}],"outputs":[]}]

How It Works​

Weekly Cycle​

The burner does not keep its own schedule. It reads the weekly calendar of the FeeCollector through epoch_time_frame:

EpochDays of the weekWhat happens in the burner
SLEEP0 – 4Nothing is sold. The only time resync_target can be called.
COLLECT4 – 5FeeCollector.collect calls burn, which takes custody of the fee tokens and stages one lot per token.
EXCHANGE5 – 6Lots staged in this week's COLLECT epoch are for sale. The price decays from start_total to floor_total.
FORWARD6 – 7Proceeds are already in the FeeCollector and are forwarded to the Hooker.

Every lot trades for exactly one EXCHANGE epoch, so auction_length equals the length of the EXCHANGE epoch (86400 seconds on the current deployments). A lot that is not sold out by the end of its window stays in the burner. It is staged again, starting from the top of the curve, the next time FeeCollector.collect runs during a COLLECT epoch.

Lots and Inventory​

A lot is a record of (staged_at, initial_amount). initial_amount is the token's full burner balance at staging time. It sets the unit price and caps how much of the lot can be sold. The amount that can be sold right now is:

available=min⁡(initial_amount,balanceOf(burner))\text{available} = \min(\text{initial\_amount}, \text{balanceOf}(\text{burner}))

Partial fills do not resize the lot or restart its curve. Tokens sent to the burner after the snapshot can be sold along the same curve, but available never goes above initial_amount.

A lot can only be filled when all of the following hold:

  • the lot was staged after the most recent resync_target call (any lot staged in or before that block is stale);
  • the current time is inside the lot's window [start, end);
  • the FeeCollector's target() still equals the burner's want;
  • FeeCollector.can_exchange([token]) returns true, so the token is not killed in the FeeCollector.

The burner itself has no kill switch. Fills are stopped through the FeeCollector kill masks (set_killed), and external settlement rails are stopped by disabling their adapter in the AdapterRegistry.

Price Curve​

The total price of a full lot, denominated in want, decays exponentially and in discrete steps. Equal time gives the same percentage drop. Let SS be start_total, FF be floor_total, kk the current step and KK the number of decay steps:

k=⌊t−startstep_duration⌋,K=⌊auction_length−1step_duration⌋k = \left\lfloor \frac{t - \text{start}}{\text{step\_duration}} \right\rfloor, \qquad K = \left\lfloor \frac{\text{auction\_length} - 1}{\text{step\_duration}} \right\rfloor P(k)={Sk=0exp⁡(ln⁡S−ln⁡SF⋅kK)0<k<KFk≥KP(k) = \begin{cases} S & k = 0 \\ \exp\left(\ln S - \ln\frac{S}{F} \cdot \frac{k}{K}\right) & 0 < k < K \\ F & k \geq K \end{cases}

The middle branch is clamped into [F,S][F, S]. The payment for amount tokens of a lot is the proportional share of the lot price, rounded up:

payment=⌈P(k)⋅amountinitial_amount⌉\text{payment} = \left\lceil \frac{P(k) \cdot \text{amount}}{\text{initial\_amount}} \right\rceil

The logarithms are evaluated in WAD fixed point using Snekmate's wad_ln/wad_exp. All rounding favours the FeeCollector. All deployments use auction_length=86400\text{auction\_length} = 86400. With step_duration=30\text{step\_duration} = 30 (Gnosis, Polygon, Fraxtal, Arbitrum, Base) the curve has K=2879K = 2879 steps; with step_duration=36\text{step\_duration} = 36 (Ethereum) it has K=2399K = 2399. In both cases the floor is reached in the last step of the window.

Settlement Rails​

There are two ways to buy from a lot. Both are priced against the live curve:

  • Native take: take / take_with_limits transfer lot tokens to the taker and then pull the quoted want payment from the caller. An optional callback lets the taker source the payment from the received tokens first.
  • Registry adapters: external protocols settle orders where the burner is the order owner, using ERC-1271 signatures of the form adapter_address (20 bytes) ++ payload. isValidSignature forwards the payload to the adapter, if the adapter is active in the AdapterRegistry. The adapter usually prices the order through check_order. Executors of active adapters get token allowances via the permissionless sync_executor_approvals. Adapters are managed in the AdapterRegistry.

Lot Staging​

burn​

DutchAuctionBurner.burn(_coins: DynArray[IERC20, MAX_COINS], _receiver: address)
Guarded Method

This function can only be called by the FeeCollector, which calls it from its permissionless collect function during the COLLECT epoch. It also reverts with TargetChanged if the FeeCollector's target() no longer matches the burner's want (see resync_target).

Function to take custody of the fee tokens and stage a lot for each of them. For each coin, the burner first pays the COLLECT keeper incentive from the FeeCollector's balance to _receiver (balance * fee(COLLECT) / 1e18). It then pulls the remaining balance into the burner and snapshots the burner's full balance of that coin as the lot's initial_amount. The lot trades during the EXCHANGE epoch of the same week.

Staging does not set any allowances. After a collect, keepers call sync_executor_approvals so that active adapters' executors can pull the staged tokens.

InputTypeDescription
_coinsDynArray[IERC20, MAX_COINS]Sorted tokens supplied by the FeeCollector; at most 64
_receiveraddressReceiver of the FeeCollector COLLECT incentive

Emits: LotStaged event.

<>Source code▼
fee_collector: public(immutable(IFeeCollector))

@external
def burn(_coins: DynArray[IERC20, c.MAX_COINS], _receiver: address):
"""
@notice Pay the COLLECT incentive, take custody, and snapshot upcoming lots.
@dev Staging touches no allowances: the keeper follows up with the
permissionless sync_executor_approvals so the staged tokens become
pullable by active adapters. Restaging a leftover lot needs no fresh
fees: a permissionless FeeCollector.collect during any later COLLECT
frame re-snapshots the burner's full balance for the upcoming week
from the top of the curve.
@param _coins Sorted tokens supplied by FeeCollector.
@param _receiver Receiver of the FeeCollector COLLECT incentive.
"""
assert msg.sender == self.fee_collector.address, OnlyFeeCollector()
assert self._target_is_current(), TargetChanged()

fee: uint256 = staticcall self.fee_collector.fee(IFeeCollector.Epoch.COLLECT, block.timestamp)
fee_payouts: DynArray[IFeeCollector.Transfer, c.MAX_COINS] = []
custody_transfers: DynArray[IFeeCollector.Transfer, c.MAX_COINS] = []

for coin: IERC20 in _coins:
collector_balance: uint256 = staticcall coin.balanceOf(self.fee_collector.address)
fee_payouts.append(
IFeeCollector.Transfer(
coin=coin.address,
to=_receiver,
amount=collector_balance * fee // c.WAD,
)
)
custody_transfers.append(
IFeeCollector.Transfer(coin=coin.address, to=self, amount=max_value(uint256))
)

extcall self.fee_collector.transfer(fee_payouts)
extcall self.fee_collector.transfer(custody_transfers)

for coin: IERC20 in _coins:
dutch_auction._stage_lot(coin)

@internal
@view
def _target_is_current() -> bool:
return staticcall self.fee_collector.target() == dutch_auction.want.address

@internal
@view
def _exchange_frame(_timestamp: uint256) -> (uint256, uint256):
return staticcall self.fee_collector.epoch_time_frame(IFeeCollector.Epoch.EXCHANGE, _timestamp)

@override(dutch_auction)
@view
def _lot_start(_token: IERC20, _staged_at: uint256) -> uint256:
exchange_start: uint256 = 0
exchange_end: uint256 = 0
exchange_start, exchange_end = self._exchange_frame(_staged_at)
return exchange_start
▶Example▼
# called by the FeeCollector during the COLLECT epoch
>>> FeeCollector.collect(["0xc2132D05D31c914a87C6611C10748AEb04B58e8F", "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619"], "0xKeeper")

Auction Configuration​

want​

DutchAuctionBurner.want() -> IERC20: view

Getter for the payment token that lots are sold for. It mirrors the FeeCollector's target() at deployment and only changes through resync_target, so the payment token can never change during a live window. The payment token is never sold as a lot.

Returns: payment token (IERC20).

<>Source code▼
exports: (
...
dutch_auction.want,
...
)
▶Example▼
>>> DutchAuctionBurner.want()   # Polygon
'0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359' # USDC

receiver​

DutchAuctionBurner.receiver() -> address: view

Getter for the receiver of every payment. The burner sets it to the FeeCollector at deployment and has no function to change it.

Returns: proceeds receiver (address).

<>Source code▼
exports: (
...
dutch_auction.receiver,
...
)
▶Example▼
>>> DutchAuctionBurner.receiver()   # Polygon
'0xf03591c62A57F71f5EbD774453db57ADCC299a6a' # FeeCollector

start_total​

DutchAuctionBurner.start_total() -> uint256: view

Getter for the price of a full lot, in raw want units, at the start of its window. Every lot uses the same value whatever its size, so the configured start total assumes no staged lot is worth more than this amount. It can be changed through resync_target.

Returns: full-lot start price (uint256).

<>Source code▼
exports: (
...
dutch_auction.start_total,
...
)
▶Example▼
>>> DutchAuctionBurner.start_total()   # Polygon, 100,000 USDC
100000000000

floor_total​

DutchAuctionBurner.floor_total() -> uint256: view

Getter for the price of a full lot, in raw want units, at the end of its window. The curve reaches this price at the window's last active step and stays there. It can be changed through resync_target.

Returns: full-lot floor price (uint256).

<>Source code▼
exports: (
...
dutch_auction.floor_total,
...
)
▶Example▼
>>> DutchAuctionBurner.floor_total()   # Polygon, 5 USDC
5000000

step_duration​

DutchAuctionBurner.step_duration() -> uint256: view

Getter for the length of one price step, in seconds. The price stays the same within a step. It can be changed through resync_target.

Returns: seconds per price step (uint256).

<>Source code▼
exports: (
...
dutch_auction.step_duration,
...
)
▶Example▼
>>> DutchAuctionBurner.step_duration()   # Polygon
30

auction_length​

DutchAuctionBurner.auction_length() -> uint256: view

Getter for the length of every lot window, in seconds. It is fixed at deployment to the length of the FeeCollector's EXCHANGE epoch. Windows exclude their end, so the curve reaches the floor at second auction_length - 1.

Returns: window length in seconds (uint256).

<>Source code▼
exports: (
dutch_auction.auction_length,
...
)

@deploy
def __init__(
_fee_collector: IFeeCollector,
_start_total: uint256,
_floor_total: uint256,
_step_duration: uint256,
_registry: address,
):
...
exchange_start: uint256 = 0
exchange_end: uint256 = 0
exchange_start, exchange_end = self._exchange_frame(block.timestamp)
assert exchange_end > exchange_start, BadExchangeFrame()
dutch_auction.__init__(
IERC20(configured_target),
_fee_collector.address,
_start_total,
_floor_total,
_step_duration,
exchange_end - exchange_start,
)
...
▶Example▼
>>> DutchAuctionBurner.auction_length()
86400

fee_collector​

DutchAuctionBurner.fee_collector() -> IFeeCollector: view

Getter for the FeeCollector contract, fixed at deployment. The FeeCollector is the only caller of burn and receives all proceeds and recovered funds. The burner also reads its roles, epoch calendar, kill masks and payment token from it.

Returns: FeeCollector (IFeeCollector).

<>Source code▼
fee_collector: public(immutable(IFeeCollector))
▶Example▼
>>> DutchAuctionBurner.fee_collector()   # Polygon
'0xf03591c62A57F71f5EbD774453db57ADCC299a6a'

resync_target​

DutchAuctionBurner.resync_target(_expected_target: address, _start_total: uint256, _floor_total: uint256, _step_duration: uint256)
Guarded Method

This function can only be called by the owner of the burner. The burner has no owner of its own: it reads owner() live from the FeeCollector, so whoever owns the FeeCollector controls this function. It can only be called during the FeeCollector's SLEEP epoch.

Function to set the payment token to the current FeeCollector.target() and to set a new price curve. It can also be used to retune the curve without changing the payment token.

The new payment token is always read from the FeeCollector and is never passed in. _expected_target makes the call revert if the FeeCollector's target changed again after the governance vote was drafted, so curve parameters cannot end up applied to the wrong token.

Every call makes all lots staged up to and including the current block stale, so they can never be filled. Because the call is only allowed during SLEEP, this only affects previous weeks' lots, and the new configuration applies from the next COLLECT epoch. If the FeeCollector changes its target and this function has not been called yet, burn reverts and all fills stop. Calling FeeCollector.set_target and this function in the same SLEEP epoch avoids that. After a target change, the old target token becomes a regular token that can be sold.

InputTypeDescription
_expected_targetaddressTarget token the new curve parameters were tuned for; must equal FeeCollector.target()
_start_totaluint256Full-lot price in want at the window start
_floor_totaluint256Full-lot price in want at the window end; 0 < _floor_total <= _start_total
_step_durationuint256Seconds per price step; the window must hold at least one step

Emits: EconomicsSet event.

<>Source code▼
@external
def resync_target(
_expected_target: address,
_start_total: uint256,
_floor_total: uint256,
_step_duration: uint256,
):
"""
@notice Re-pin the payment token to the current fee_collector.target() with
a curve retuned for it. Also serves as a same-target curve retune.
...
"""
roles._check_owner()
new_target: address = staticcall self.fee_collector.target()
assert new_target != empty(address), BadTarget()
assert new_target == _expected_target, TargetChanged()

sleep_start: uint256 = 0
sleep_end: uint256 = 0
sleep_start, sleep_end = staticcall self.fee_collector.epoch_time_frame(
IFeeCollector.Epoch.SLEEP, block.timestamp
)
assert sleep_start <= block.timestamp and block.timestamp < sleep_end, NotSleepEpoch()

dutch_auction._set_economics(
IERC20(new_target),
_start_total,
_floor_total,
_step_duration,
)
▶Example▼
# during SLEEP, after FeeCollector.set_target(new_target)
>>> DutchAuctionBurner.resync_target(new_target, 100000000000, 5000000, 30)

Lots and Pricing​

lots​

DutchAuctionBurner.lots(arg0: IERC20) -> Lot: view

Getter for a token's lot record. staged_at is 0 for a token that was never staged. The price curve is not stored in the lot; it is always read from the current configuration.

InputTypeDescription
arg0IERC20Lot token

Returns: Lot struct consisting of staged_at (uint256), the staging timestamp, and initial_amount (uint256), the balance snapshot.

<>Source code▼
exports: (
...
dutch_auction.lots,
...
)
▶Example▼
>>> DutchAuctionBurner.lots("0xc2132D05D31c914a87C6611C10748AEb04B58e8F")
(1795401011, 1523450012)

window​

DutchAuctionBurner.window(_token: address, _timestamp: uint256 = 0) -> (uint256, uint256): view

Getter for a lot's trading window [start, end). By default it returns the window of the token's current lot, or (0, 0) for a token that was never staged. If _timestamp is given, it returns the window a lot staged at that time would get. The window can be in the future (a lot staged before its EXCHANGE epoch) or in the past (a leftover). Use available to check whether a lot can actually be filled, because kill masks and stale lots also stop fills.

InputTypeDescription
_tokenaddressLot token
_timestampuint256Staging time to evaluate; 0 (default) reads the token's lot

Returns: window start, inclusive (uint256), and window end, exclusive (uint256).

<>Source code▼
@override(dutch_auction)
@view
def _lot_start(_token: IERC20, _staged_at: uint256) -> uint256:
exchange_start: uint256 = 0
exchange_end: uint256 = 0
exchange_start, exchange_end = self._exchange_frame(_staged_at)
return exchange_start

@internal
@view
def _exchange_frame(_timestamp: uint256) -> (uint256, uint256):
return staticcall self.fee_collector.epoch_time_frame(IFeeCollector.Epoch.EXCHANGE, _timestamp)
▶Example▼
>>> DutchAuctionBurner.window("0xc2132D05D31c914a87C6611C10748AEb04B58e8F")
(1795478400, 1795564800)

available​

DutchAuctionBurner.available(_from: address) -> uint256: view

Getter for the amount of a token that can be taken right now: min(initial_amount, balanceOf(burner)). Returns 0 if the lot is not active, meaning it is outside its window, stale after a resync_target, killed in the FeeCollector, or the FeeCollector's target has changed.

InputTypeDescription
_fromaddressLot token

Returns: amount available to take (uint256).

<>Source code▼
@override(dutch_auction)
@view
def _sellable(_token: address) -> bool:
return self._target_is_current() and staticcall self.fee_collector.can_exchange([_token])
▶Example▼
>>> DutchAuctionBurner.available("0xc2132D05D31c914a87C6611C10748AEb04B58e8F")
1523450012

price​

DutchAuctionBurner.price(_from: address, _ts: uint256 = block.timestamp) -> uint256: view

Getter for the unit price of a lot token: the raw want amount per 1e18 raw units of _from, rounded up. This is a quote with 1e18 precision, not a token-decimal-adjusted price. getAmountNeeded gives the exact payment. If _ts is given, only the window check and the curve are evaluated at that time; the balance and sellability are still read at the current block. A projection is therefore only meaningful while fills are currently allowed, and returns 0 outside an open EXCHANGE epoch.

InputTypeDescription
_fromaddressLot token
_tsuint256Timestamp to evaluate at; defaults to now

Returns: unit price in raw want per 1e18 raw units of _from; 0 for an inactive lot (uint256).

<>Source code▼
exports: (
...
dutch_auction.price,
...
)
▶Example▼
>>> DutchAuctionBurner.price("0xc2132D05D31c914a87C6611C10748AEb04B58e8F")
1000412577089

getAmountNeeded​

DutchAuctionBurner.getAmountNeeded(_from: address, amountToTake: uint256 = max_value(uint256), _ts: uint256 = block.timestamp) -> uint256: view

Getter for the exact want payment needed to take amountToTake of a lot token, rounded up. This is the payment a native take pulls. Passing max_value(uint256) (the default) quotes everything available, which matches Yearn's single-argument overload. If _ts is given, only the window check and the curve are evaluated at that time; the balance and sellability are read at the current block. Reverts with AmountExceedsAvailable if amountToTake is larger than available.

InputTypeDescription
_fromaddressLot token
amountToTakeuint256Amount of _from to quote; defaults to everything available
_tsuint256Timestamp to evaluate at; defaults to now

Returns: want payment for amountToTake; 0 for an inactive lot (uint256).

<>Source code▼
exports: (
...
dutch_auction.getAmountNeeded,
...
)
▶Example▼
>>> DutchAuctionBurner.getAmountNeeded("0xc2132D05D31c914a87C6611C10748AEb04B58e8F", 1000000000)
1000412578

Native Settlement​

Native takes are the burner's own settlement rail. The lot tokens are transferred to the receiver first, an optional callback runs, and then the full quoted payment is pulled with transferFrom from the caller's want allowance and sent to the FeeCollector. The caller must have approved the burner for want beforehand. Example takers are the periphery contracts AuctionTaker.vy and DutchAuctionResolver.vy.

If data is non-empty, the receiver is called with:

interface AuctionTaker:
def auctionTakeCallback(
_from: address,
_sender: address,
_amount_taken: uint256,
_amount_needed: uint256,
_data: Bytes[INF],
): nonpayable

The burner has a contract-wide reentrancy lock. While a callback is running, only the configuration getters (want, receiver, start_total, floor_total, step_duration, lots, window) can be called; quotes and availability views are locked.

take​

DutchAuctionBurner.take(_from: address, maxAmount: uint256 = max_value(uint256), takerReceiver: address = msg.sender, data: Bytes[INF] = b"") -> uint256

Function to buy up to maxAmount of a lot token at the current curve price. The defaults match Yearn's shorter take overloads: everything available, to the caller, with no callback. A price within a window can never change (see resync_target), so this function has no payment limit. Use take_with_limits to also bound inclusion time, minimum amount and maximum payment.

InputTypeDescription
_fromaddressLot token to buy
maxAmountuint256Maximum amount of _from to take; defaults to all
takerReceiveraddressReceiver of the lot tokens; defaults to the caller
dataBytes[INF]Data forwarded to takerReceiver.auctionTakeCallback; no callback if empty

Returns: amount of _from taken (uint256).

Emits: Taken event.

<>Source code▼
exports: (
...
dutch_auction.take,
...
)
▶Example▼
>>> USDC.approve(DutchAuctionBurner, 2000000000)
>>> DutchAuctionBurner.take("0xc2132D05D31c914a87C6611C10748AEb04B58e8F")
1523450012

take_with_limits​

DutchAuctionBurner.take_with_limits(_from: address, _max_amount: uint256, _min_amount: uint256, _max_payment: uint256, _receiver: address, _deadline: uint256, _data: Bytes[INF]) -> (uint256, uint256)

Function to buy from a lot with explicit limits that are checked when the transaction is included. It reverts with Deadline after _deadline, with InsufficientAmount if less than _min_amount would be taken, and with ExcessivePayment if the payment would be higher than _max_payment. Combine _deadline with window to keep the take inside the intended lot window.

InputTypeDescription
_fromaddressLot token to buy
_max_amountuint256Maximum amount of _from to take
_min_amountuint256Minimum amount of _from to take
_max_paymentuint256Maximum want payment
_receiveraddressReceiver of the lot tokens
_deadlineuint256Last timestamp (inclusive) at which the take may execute
_dataBytes[INF]Data forwarded to _receiver.auctionTakeCallback; no callback if empty

Returns: amount of _from taken (uint256) and want payment pulled (uint256).

Emits: Taken event.

<>Source code▼
exports: (
...
dutch_auction.take_with_limits,
...
)
▶Example▼
>>> DutchAuctionBurner.take_with_limits("0xc2132D05D31c914a87C6611C10748AEb04B58e8F", 1000000000, 1000000000, 1001000000, "0xTaker", 1795500000, b"")
(1000000000, 1000412578)

Signed-Order Settlement​

External settlement protocols plug in through the AdapterRegistry. The FeeCollector owner registers an adapter with its executor (the contract that pulls the sold tokens) and activates it. The registry owner or emergency owner can disable an adapter, which stops routing for every auction reading that registry immediately. All signatures have the same format:

signature = adapter_address (20 bytes) ++ payload

The signature bytes carry no authority. They only pass the order to the adapter, which rebuilds the protocol digest from the payload, compares it with the hash, and then prices the order through check_order. For CoW Protocol, the CowAdapter uses eip1271 orders with from = burner and signature CowAdapter ++ abi.encode(order). Its registry entry uses the GPv2 vault relayer as executor.

warning

Disabling an adapter in the registry does not clear its executor's allowances on the burner. Batch registry.disable_adapter(adapter) with sync_executor_approvals(executor, tokens) in one transaction.

check_order​

DutchAuctionBurner.check_order(_sell_token: address, _buy_token: address, _receiver: address, _sell_amount: uint256, _min_buy_amount: uint256, _valid_to: uint256) -> bool: view

Function that checks the economics of a signed order, offered to settlement adapters so that pricing rules are in one place. It returns true for an order that can be filled and otherwise reverts with a specific error, so an eth_call shows why an order cannot be filled from the error selector alone. The signature router does not enforce this check: an adapter that skips it sells by its own rules, so listing an adapter in the registry is the owner's responsibility.

The order must buy want, pay the FeeCollector, sell at most the lot's initial_amount (partial-fill totals are compared to the snapshot, not to the remaining balance), expire no later than the window end, and ask for at least the live curve quote for _sell_amount.

InputTypeDescription
_sell_tokenaddressLot token the order sells
_buy_tokenaddressToken the order buys; must be want
_receiveraddressReceiver of the bought tokens; must be receiver
_sell_amountuint256Total sell amount; 0 < _sell_amount <= initial_amount
_min_buy_amountuint256Minimum buy amount; at least the live quote for _sell_amount
_valid_touint256Last timestamp (inclusive) the order is valid; between now and the window end

Returns: true for an order that can be filled (bool). Otherwise it reverts with BadBuyToken, BadReceiver, LotInactive, NothingAvailable, BadSellAmount, BadValidTo or BadBuyAmount.

<>Source code▼
exports: (
...
dutch_auction.check_order,
)
▶Example▼
>>> DutchAuctionBurner.check_order("0xc2132D05D31c914a87C6611C10748AEb04B58e8F", "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", "0xf03591c62A57F71f5EbD774453db57ADCC299a6a", 1000000000, 1000500000, 1795500000)
True

isValidSignature​

DutchAuctionBurner.isValidSignature(_hash: bytes32, _signature: Bytes[INF]) -> bytes4: view

ERC-1271 signature validation, used by settlement protocols to validate orders owned by the burner. The first 20 bytes of _signature are read as the adapter address. If that adapter is active in the AdapterRegistry, the rest of the signature (the payload) is forwarded to the adapter's isValidSignature(_hash, payload) with a staticcall, and any revert from the adapter is passed through unchanged. A signature shorter than 20 bytes or with an inactive or unknown adapter returns 0xffffffff. The registry is checked live on every call, so disabling an adapter stops settlement immediately.

InputTypeDescription
_hashbytes32Settlement digest being signed
_signatureBytes[INF]Adapter address (20 bytes) followed by its payload

Returns: ERC-1271 magic value 0x1626ba7e for a valid signature, 0xffffffff otherwise (bytes4).

<>Source code▼
exports: (
adapters.registry,
adapters.sync_executor_approvals,
adapters.isValidSignature,
)
▶Example▼
>>> DutchAuctionBurner.isValidSignature(order_digest, concat(cow_adapter, abi_encode(order)))
0x1626ba7e

sync_executor_approvals​

DutchAuctionBurner.sync_executor_approvals(_executor: address, _tokens: DynArray[IERC20, MAX_COINS])

Permissionless function to bring an executor's token allowances in line with the registry. If registry.is_executor_active(_executor) is true, each token is approved to max_value(uint256) (only if the current allowance is zero). Otherwise each token's allowance is set to zero. Keepers call it after every collect so active executors can pull staged tokens. The same call is used to clean up allowances after an adapter is disabled. Several adapters can share one executor, so disabling one adapter does not revoke allowances while another active adapter still uses the same executor.

InputTypeDescription
_executoraddressExecutor whose allowances are synced
_tokensDynArray[IERC20, MAX_COINS]Tokens to sync; at most 64
<>Source code▼
exports: (
adapters.registry,
adapters.sync_executor_approvals,
adapters.isValidSignature,
)
▶Example▼
>>> vault_relayer = AdapterRegistry.get_adapter(CowAdapter).executor
>>> DutchAuctionBurner.sync_executor_approvals(vault_relayer, ["0xc2132D05D31c914a87C6611C10748AEb04B58e8F"])

registry​

DutchAuctionBurner.registry() -> IAdapterRegistry: view

Getter for the AdapterRegistry, which decides signature routing and executor allowances. It is fixed at deployment. A registry with no active adapters means only native takes are possible.

Returns: AdapterRegistry (IAdapterRegistry).

<>Source code▼
exports: (
adapters.registry,
...
)
▶Example▼
>>> DutchAuctionBurner.registry()   # Polygon
'0xEb4b6A015AB06aad3C9EEDd3b8cf6116bF484961'

Yearn Auction Compatibility​

The quote and take functions use the selector names of Yearn's Auction.sol (want, available, price, getAmountNeeded, take), including all of Yearn's overloads, so Yearn tooling can drive the burner. The three views below come from the separate yearn_auction.vy module. Yearn's kick, kickable and governance setters are not implemented.

isActive​

DutchAuctionBurner.isActive(_from: address) -> bool: view

Getter for whether a lot token can be taken right now.

InputTypeDescription
_fromaddressLot token

Returns: true while available(_from) is positive (bool).

<>Source code▼
exports: (
yearn_auction.isActive,
yearn_auction.auctionLength,
yearn_auction.auctions,
)
▶Example▼
>>> DutchAuctionBurner.isActive("0xc2132D05D31c914a87C6611C10748AEb04B58e8F")
True

auctionLength​

DutchAuctionBurner.auctionLength() -> uint256: view

Getter for the length of every auction window. Same value as auction_length.

Returns: window length in seconds (uint256).

<>Source code▼
exports: (
yearn_auction.isActive,
yearn_auction.auctionLength,
yearn_auction.auctions,
)
▶Example▼
>>> DutchAuctionBurner.auctionLength()
86400

auctions​

DutchAuctionBurner.auctions(_from: address) -> AuctionInfo: view

Getter for a lot in Yearn's record format. kicked is the start of the lot's window. It can be in the future, so Yearn readers should check isActive rather than subtract kicked from the current time. scaler is always 1 because price is already a raw quote with 1e18 precision, so Yearn's amount * scaler * price / 1e18 reproduces getAmountNeeded up to rounding. Returns all zeros for a token that was never staged.

InputTypeDescription
_fromaddressLot token

Returns: AuctionInfo struct consisting of kicked (uint64), scaler (uint64) and initialAvailable (uint128).

<>Source code▼
exports: (
yearn_auction.isActive,
yearn_auction.auctionLength,
yearn_auction.auctions,
)
▶Example▼
>>> DutchAuctionBurner.auctions("0xc2132D05D31c914a87C6611C10748AEb04B58e8F")
(1795478400, 1, 1523450012)

Pushing and Recovering Coins​

push_target​

DutchAuctionBurner.push_target() -> uint256

Permissionless function to send the burner's entire want balance to the FeeCollector. Payments from native takes go directly to the FeeCollector, so this only handles want tokens that ended up in the burner some other way.

Returns: amount of want sent (uint256).

<>Source code▼
@external
def push_target() -> uint256:
"""
@notice Permissionlessly return target tokens held by this burner.
@return Amount of target returned.
"""
amount: uint256 = staticcall dutch_auction.want.balanceOf(self)
if amount != 0:
assert extcall dutch_auction.want.transfer(
self.fee_collector.address, amount, default_return_value=True
)
return amount
▶Example▼
>>> DutchAuctionBurner.push_target()
0

recover​

DutchAuctionBurner.recover(_coins: DynArray[IERC20, MAX_COINS])
Guarded Method

This function can only be called by the owner of the burner, which is read live from the FeeCollector. The FeeCollector's emergency owner cannot call it.

Function to send the full balance of the given tokens, or of the native coin, back to the FeeCollector. It cannot send funds anywhere else. Emptying a token's balance also ends its lot, because available uses the balance. During the same week's COLLECT epoch, a permissionless collect can pull the token back and stage it again, so an evacuation should batch recover with FeeCollector.set_killed.

InputTypeDescription
_coinsDynArray[IERC20, MAX_COINS]Tokens to return in full; 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for the native coin

Emits: Recovered event.

<>Source code▼
@external
def recover(_coins: DynArray[IERC20, c.MAX_COINS]):
roles._check_owner()

for coin: IERC20 in _coins:
recovery._recover_coin(coin, self.fee_collector.address)
▶Example▼
>>> DutchAuctionBurner.recover(["0xc2132D05D31c914a87C6611C10748AEb04B58e8F"])

Contract Ownership​

The burner stores no roles of its own. owner is read live from the FeeCollector on every call, so ownership always follows the FeeCollector and is transferred there, not on the burner.

owner​

DutchAuctionBurner.owner() -> address: view

Getter for the owner of the burner, read live from FeeCollector.owner().

Returns: owner (address).

<>Source code▼
initializes: roles

exports: roles.owner

@deploy
def __init__(...):
...
roles.__init__(roles.RoleSource(_fee_collector.address))
...
▶Example▼
>>> DutchAuctionBurner.owner()
'0x71F718D3e4d1449D1502A6A7595eb84eBcCB1683'

Other Methods​

VERSION​

DutchAuctionBurner.VERSION() -> String[20]: view

Getter for the burner version.

Returns: version (String[20]).

<>Source code▼
VERSION: public(constant(String[20])) = "DutchAuction"
▶Example▼
>>> DutchAuctionBurner.VERSION()
'DutchAuction'

supportsInterface​

DutchAuctionBurner.supportsInterface(_interface_id: bytes4) -> bool: view

ERC-165 interface detection. The burner reports ERC-165 (0x01ffc9a7), the FeeCollector burner interface (0xa3b5e311, the XOR of burn, push_target and VERSION), and ERC-1271 (0x1626ba7e). ERC-1271 is always reported, even when no adapter is active.

InputTypeDescription
_interface_idbytes4ERC-165 interface ID

Returns: whether the interface is supported (bool).

<>Source code▼
@external
@view
@reentrant
def supportsInterface(_interface_id: bytes4) -> bool:
return _interface_id in [c.ERC165_INTERFACE_ID, c.BURNER_INTERFACE_ID, c.ERC1271_MAGIC_VALUE]
▶Example▼
>>> DutchAuctionBurner.supportsInterface("0xa3b5e311")
True