Skip to main content

AdapterRegistry

The AdapterRegistry is the list of external settlement adapters that a DutchAuctionBurner may route orders to. Each entry stores an adapter (the contract that validates orders for one settlement protocol, e.g. CowAdapter), its executor (the protocol contract that pulls the sold tokens from the burner, e.g. CoW Protocol's vault relayer) and an activation flag.

The burner reads the registry live on every signature check and allowance sync. An adapter only receives orders while it is active, and auctions only grant token allowances to an executor while at least one active adapter uses it. The registry holds no tokens, calls no external protocols and never runs an adapter's code.

AdapterRegistry.vy

The source code for the AdapterRegistry.vy contract can be found on GitHub. The contract is written in Vyper version 0.5.0b1 for the cancun EVM version. Roles are handled by the shared roles.vy module.

Each DutchAuctionBurner reads its own registry, set at deployment:

{ }Contract ABI▼
[{"name":"AdapterSet","inputs":[{"name":"adapter","type":"address","indexed":true},{"name":"executor","type":"address","indexed":true}],"anonymous":false,"type":"event"},{"name":"AdapterActivated","inputs":[{"name":"adapter","type":"address","indexed":true}],"anonymous":false,"type":"event"},{"name":"AdapterDisabled","inputs":[{"name":"adapter","type":"address","indexed":true}],"anonymous":false,"type":"event"},{"name":"BadAdapter","inputs":[],"type":"error"},{"name":"UnknownAdapter","inputs":[],"type":"error"},{"name":"AlreadyActive","inputs":[],"type":"error"},{"name":"NotActive","inputs":[],"type":"error"},{"name":"BadRoleSource","inputs":[],"type":"error"},{"name":"OnlyOwner","inputs":[],"type":"error"},{"name":"OnlyOwnerOrEmergency","inputs":[],"type":"error"},{"stateMutability":"view","type":"function","name":"role_source","inputs":[],"outputs":[{"name":"","type":"address"}]},{"stateMutability":"view","type":"function","name":"owner","inputs":[],"outputs":[{"name":"","type":"address"}]},{"stateMutability":"view","type":"function","name":"emergency_owner","inputs":[],"outputs":[{"name":"","type":"address"}]},{"stateMutability":"view","type":"function","name":"get_adapter","inputs":[{"name":"_adapter","type":"address"}],"outputs":[{"name":"","type":"tuple","components":[{"name":"executor","type":"address"},{"name":"active","type":"bool"}]}]},{"stateMutability":"view","type":"function","name":"get_adapters","inputs":[],"outputs":[{"name":"","type":"address[]"}]},{"stateMutability":"view","type":"function","name":"is_executor_active","inputs":[{"name":"_executor","type":"address"}],"outputs":[{"name":"","type":"bool"}]},{"stateMutability":"nonpayable","type":"function","name":"set_adapter","inputs":[{"name":"_adapter","type":"address"},{"name":"_executor","type":"address"}],"outputs":[]},{"stateMutability":"nonpayable","type":"function","name":"activate_adapter","inputs":[{"name":"_adapter","type":"address"}],"outputs":[]},{"stateMutability":"nonpayable","type":"function","name":"disable_adapter","inputs":[{"name":"_adapter","type":"address"}],"outputs":[]},{"stateMutability":"nonpayable","type":"constructor","inputs":[{"name":"_role_source","type":"address"}],"outputs":[]}]

How It Works​

Roles​

The registry stores no roles of its own. owner and emergency_owner are read live from the FeeCollector (the role_source) on every call, so they always match the FeeCollector's roles.

ActionFunctionWho can call it
Register, repoint or remove an adapterset_adapterowner
Activate an adapteractivate_adapterowner
Disable an adapterdisable_adapterowner or emergency_owner

The emergency owner can switch an adapter off immediately, but can never add or re-enable one. Adapters cannot register themselves, so listing an adapter is the owner's review: an active adapter's executor gets unlimited allowances on the burner's lot tokens.

Adapter Lifecycle​

  • New entries are always stored inactive, so registering an adapter never makes it live on its own. Nothing stops the owner from batching set_adapter and activate_adapter in one transaction.
  • An active adapter cannot be changed with set_adapter; it must be disabled first. This keeps executor reference counts consistent.
  • The registry holds at most 32 adapters.

Executors and Allowances​

Several adapters can share one executor. For example, every protocol in the Permit2 family pulls tokens through Permit2 itself. The registry therefore keeps a reference count per executor: activate_adapter increments it, disable_adapter decrements it, and is_executor_active returns true while it is positive.

The registry does not touch token allowances itself. Each burner's permissionless sync_executor_approvals(executor, tokens) reads is_executor_active and sets each token's allowance to unlimited or to zero. As a result:

  • After activating an adapter, sync_executor_approvals must be called on the burner so the executor can pull lot tokens.
  • Disabling an adapter stops signature routing at once, but its executor's existing allowances stay in place until sync_executor_approvals is called. Batch disable_adapter with sync_executor_approvals(executor, tokens) in one transaction.
  • If another active adapter still uses the same executor, is_executor_active stays true after a disable and the allowances are kept, which is the intended behaviour.

Adapter Catalog​

get_adapter​

AdapterRegistry.get_adapter(_adapter: address) -> AdapterConfig: view

Getter for an adapter's configuration. An unknown adapter returns a zeroed config (executor == empty(address)), which the burner's signature router treats as invalid.

InputTypeDescription
_adapteraddressAdapter contract

Returns: AdapterConfig struct consisting of executor (address), the contract that pulls sold tokens, and active (bool), whether the adapter is active.

<>Source code▼
configs: HashMap[address, IAdapterRegistry.AdapterConfig]

@external
@view
def get_adapter(_adapter: address) -> IAdapterRegistry.AdapterConfig:
"""
@notice Read an adapter's config.
@param _adapter Adapter contract.
@return Stored config; zeroed (executor == empty(address)) when unknown.
"""
return self.configs[_adapter]
▶Example▼

get_adapters​

AdapterRegistry.get_adapters() -> DynArray[address, MAX_ADAPTERS]: view

Getter for every registered adapter, active or not, in no particular order. Removing an entry swaps the last entry into its place, so indices are not stable.

Returns: registered adapter addresses (DynArray[address, 32]).

<>Source code▼
# Registered adapters (executor set), in no particular order.
adapters: DynArray[address, c.MAX_ADAPTERS]

@external
@view
def get_adapters() -> DynArray[address, c.MAX_ADAPTERS]:
"""
@notice List every registered adapter, active or not.
@return Registered adapter addresses, in no particular order.
"""
return self.adapters
▶Example▼

is_executor_active​

AdapterRegistry.is_executor_active(_executor: address) -> bool: view

Getter for whether at least one active adapter uses an executor. Burners keep their allowances toward an executor while this returns true, via sync_executor_approvals.

InputTypeDescription
_executoraddressExecutor contract

Returns: true while at least one active adapter references the executor (bool).

<>Source code▼
# Active adapters per executor. Several adapters can share one executor (every
# permit2-family protocol pulls through Permit2 itself); auctions approve an
# executor while its count is positive.
executor_refcount: HashMap[address, uint256]

@external
@view
def is_executor_active(_executor: address) -> bool:
"""
@notice Whether an active adapter references the executor; auctions keep
their allowances toward it while this holds.
@param _executor Executor contract.
@return True while at least one active adapter references it.
"""
return self.executor_refcount[_executor] > 0
▶Example▼

Adapter Management​

set_adapter​

AdapterRegistry.set_adapter(_adapter: address, _executor: address)
Guarded Method

This function can only be called by the owner of the registry, which is read live from the FeeCollector. So adding a settlement rail is in the hands of whoever owns the FeeCollector.

Function to register an adapter, point an inactive adapter at a new executor, or remove an adapter. The entry is always stored inactive; activate_adapter is a separate step. Passing empty(address) as _executor removes the adapter from get_adapters, and it then reads as unknown. Reverts with AlreadyActive if the adapter is currently active (disable it first), and with BadAdapter for the zero address. Registering a 33rd adapter reverts.

InputTypeDescription
_adapteraddressAdapter contract
_executoraddressProtocol contract that pulls sold tokens; empty(address) removes the entry

Emits: AdapterSet event.

<>Source code▼
event AdapterSet:
adapter: indexed(address)
executor: indexed(address)

@external
def set_adapter(_adapter: address, _executor: address):
"""
@notice Register an adapter, repoint an inactive one at a new executor,
or remove it (executor == empty(address) reads as unknown and
drops it from get_adapters). Entries are stored inactive:
activation is a separate owner step, and an active adapter must
be disabled first so executor references stay consistent.
@param _adapter Adapter contract.
@param _executor Protocol contract that pulls sold tokens; the approval
target auctions grant while the adapter is active. Zero removes
the entry.
"""
roles._check_owner()
assert _adapter != empty(address), BadAdapter()
assert not self.configs[_adapter].active, AlreadyActive()

if _executor == empty(address):
self._remove_listing(_adapter)
elif self.configs[_adapter].executor == empty(address):
self.adapters.append(_adapter) # dev: too many adapters
self.configs[_adapter] = IAdapterRegistry.AdapterConfig(executor=_executor, active=False)
log AdapterSet(adapter=_adapter, executor=_executor)

@internal
def _remove_listing(_adapter: address):
# Swap-remove: order is not part of the listing's contract.
for i: uint256 in range(len(self.adapters), bound=c.MAX_ADAPTERS):
if self.adapters[i] == _adapter:
self.adapters[i] = self.adapters[len(self.adapters) - 1]
self.adapters.pop()
break
▶Example▼
>>> AdapterRegistry.set_adapter(cow_adapter, cow_adapter.vault_relayer())

activate_adapter​

AdapterRegistry.activate_adapter(_adapter: address)
Guarded Method

This function can only be called by the owner of the registry, which is read live from the FeeCollector. The emergency owner cannot activate adapters.

Function to activate a registered adapter and add a reference to its executor. From then on, burners route signatures prefixed with this adapter's address to it, and is_executor_active returns true for its executor. Burner allowances only follow once sync_executor_approvals is called on each burner. Reverts with UnknownAdapter if the adapter is not registered and with AlreadyActive if it is already active.

InputTypeDescription
_adapteraddressAdapter to activate; must be registered and inactive

Emits: AdapterActivated event.

<>Source code▼
event AdapterActivated:
adapter: indexed(address)

@external
def activate_adapter(_adapter: address):
"""
@notice Activate a registered adapter and reference its executor;
auction allowances follow through their sync_executor_approvals.
@param _adapter Adapter to activate; must exist and be inactive.
"""
roles._check_owner()
config: IAdapterRegistry.AdapterConfig = self.configs[_adapter]
assert config.executor != empty(address), UnknownAdapter()
assert not config.active, AlreadyActive()

self.configs[_adapter].active = True
self.executor_refcount[config.executor] += 1
log AdapterActivated(adapter=_adapter)
▶Example▼
>>> AdapterRegistry.activate_adapter(cow_adapter)
>>> DutchAuctionBurner.sync_executor_approvals(cow_adapter.vault_relayer(), lot_tokens)

disable_adapter​

AdapterRegistry.disable_adapter(_adapter: address)
Guarded Method

This function can be called by the owner or the emergency_owner of the registry, both read live from the FeeCollector. It is the only function the emergency owner can call, so an adapter can be switched off quickly without the emergency owner being able to add one.

Function to disable an active adapter and release its executor reference. Every burner reading this registry stops routing signatures to the adapter immediately. Native take on the burners is not affected. Token allowances are not touched: batch this call with each burner's sync_executor_approvals(executor, tokens). Reverts with NotActive if the adapter is not active.

InputTypeDescription
_adapteraddressAdapter to disable; must be active

Emits: AdapterDisabled event.

<>Source code▼
event AdapterDisabled:
adapter: indexed(address)

@external
def disable_adapter(_adapter: address):
"""
@notice Disable an active adapter and release its executor reference.
Faster than activation on purpose: the emergency owner can kill an
adapter without being able to add one.
@dev Does not touch auction allowances: batch with each auction's
sync_executor_approvals once the executor is no longer active.
@param _adapter Adapter to disable; must be active.
"""
roles._check_owner_or_emergency()
config: IAdapterRegistry.AdapterConfig = self.configs[_adapter]
assert config.active, NotActive()

self.configs[_adapter].active = False
self.executor_refcount[config.executor] -= 1
log AdapterDisabled(adapter=_adapter)
▶Example▼
# one transaction (e.g. via a multisig batch)
>>> AdapterRegistry.disable_adapter(cow_adapter)
>>> DutchAuctionBurner.sync_executor_approvals(cow_adapter.vault_relayer(), lot_tokens)

Contract Ownership​

The registry has no ownership functions of its own. Both roles are read live from the role_source (the FeeCollector), so they are changed there with FeeCollector.set_owner and FeeCollector.set_emergency_owner.

owner​

AdapterRegistry.owner() -> address: view

Getter for the owner, read live from role_source.owner().

Returns: owner (address).

<>Source code▼
initializes: roles
exports: (
roles.role_source,
roles.owner,
roles.emergency_owner,
)
▶Example▼

emergency_owner​

AdapterRegistry.emergency_owner() -> address: view

Getter for the emergency owner, read live from role_source.emergency_owner(). The emergency owner can only call disable_adapter.

Returns: emergency owner (address).

<>Source code▼
initializes: roles
exports: (
roles.role_source,
roles.owner,
roles.emergency_owner,
)
▶Example▼

role_source​

AdapterRegistry.role_source() -> RoleSource: view

Getter for the contract the roles are read from, set at deployment. On every deployment this is the chain's FeeCollector.

Returns: role source (RoleSource).

<>Source code▼
@deploy
def __init__(_role_source: roles.RoleSource):
"""
@notice Pin the role source the registry reads its owners from.
@param _role_source Contract exposing owner() and emergency_owner() views
(the FeeCollector); must answer owner() with a nonzero address.
"""
roles.__init__(_role_source)
▶Example▼