> For the complete documentation index, see [llms.txt](https://docs.efficientdex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.efficientdex.com/run-a-pool/roles-and-governance.md). # Roles and governance Who controls an Efficient pool: what each role can call, what a pause stops, how much notice each change gets and what's fixed at creation. **Each Efficient pool has its own pool operator, keeper and guardian.** The protocol Safe governs what every pool shares. Some calls need no role, and any address can make them. A pool's hooks price its fills and its fee, and recentre its anchor. The anchor is the curve's reference price. [Hooks](/how-pools-work/hooks.md) covers how they work. A few terms recur on this page: * A venue is one lending market a pool borrows from or supplies to. * A venue type is one kind of lending market that pools can use. * A loan asset is a token the pool can borrow. The first is the other token in the pool's pair: USDC, in a pool that trades BTC against USDC. Any extra token the pool can borrow is also a loan asset. A pool can run with no lending market. Calls that act on venues apply only to a pool that has them. Calls on debt or collateral apply only to a pool that borrows, or that still owes debt from before borrowing was switched off. [Risks and safeguards](/use-efficient/risks-and-safeguards.md) sums up what these powers mean for depositors in any Efficient pool. ## Roles **Four roles act on a pool, and some calls are open to any address.** | Role | Who | In short | | ------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Pool operator | The pool's owner. Ownership moves in two steps and can't be renounced | Configures the pool, schedules delayed changes, pauses and unpauses, and appoints the other roles | | Keeper | Appointed by the pool operator | Runs routine maintenance within set limits | | Guardian | Appointed by the pool operator | Pauses. Cancels scheduled hook sets, venues, loan assets and ceiling raises. Tightens limits but never loosens them | | Protocol Safe | A multisig fixed when the factory is deployed | Changes what every pool shares: pool code, venue types, the financing router's pause and the protocol fee | | Anyone | Any address | Trades, redeems, deposits where the allowlist admits it, creates pools and makes a few public maintenance calls | ### Pool operator The pool operator owns the pool and can: * schedule and execute new hook sets, venues and loan assets * retire a venue that holds nothing, and retire a loan asset for good once every venue of it is retired and empty * set the feature switches, risk limits, caps, fee bounds, oracle band, fund re-check and performance fee * set the pool-asset reserve with `setPoolAssetReserve(venueId, reserve)`. This works only at a lending market that pays a return on collateral, and Morpho Blue doesn't. * set the ceilings on the price band and the fee cap. A raise waits for the governance delay. * drop the price band with `setMarketBand(off, bandWad)` once its ceiling allows no band. It works only with no debt, borrowing off, one loan asset and an invariant hook that prices without a feed price. * attach a price band to a pool that has none, with the same call * set the hooks' owner settings, such as the Everlong hook's bounds on the keeper's tuning and its curve shape * pause and unpause the pool, the entry market and tranches * run maintenance and the emergency calls * seed the first loan asset into a new pool with `seedLeg(assets, to)`, so the pool opens two-sided. This works only while one holder owns every share. * make the first entry into each tranche, which opens it to other depositors * manage the deposit allowlist and the largest discount an entry-market request can set * whitelist the DEX routers that the asset router converts through for single-asset deposits and exits * appoint the keeper, the guardian and the fee receiver. The fee receiver is the address paid the pool operator's part of the performance fee. A pool created without an allowlist contract admits every depositor. So does an allowlist contract that the pool operator has switched off. The pool operator can make every keeper and guardian call itself. So a pool can run with no keeper or guardian appointed. The pool operator should leave the guardian unset rather than name itself, because the call that adds a venue refuses the guardian's address. An authority contract records the pool's roles. The pool's creator supplies it, and the pool operator owns it. The pool operator appoints roles on it with `setKeeper`, `setGuardian` and `setFeeReceiver`, and each takes effect at once. To hand over its own role, the pool operator calls `transferOwnership(newOwner)`. The handover takes effect only when the new address calls `acceptOwnership()`. The standard authority contract, `EverlongCore`, refuses the zero address as fee receiver. So the fee receiver is always set. ### Keeper The keeper runs routine maintenance within set limits. It can: * recentre the anchor with `recenter(minAnchorN36, maxAnchorN36, deadline)` on the pool * move the LTV pin and the credit setting with `setDials(phiWad, ltvWad)` on the pool. Moves stay inside limits fixed at creation. Each rise of the LTV pin has a step limit, and a cooldown applies between moves. * set venue order with `setPriorities(borrow_, supply_, withdraw_, repay_)` on the pool * run collateral top-ups and releases, refinancing and supply migration with `maintain(kind, a, b, amount)` on the pool. The `kind` is `TopUp`, `Release`, `Refinance` or `MigrateSupply`. Top-ups and releases are for a pool that owes debt at a lending market. * set the senior tranche's target rate with `setTargetApr(aprWad)` on the tranche controller. The rate can sit anywhere inside the range fixed when the tranches were created. * post the hooks' keeper settings where a hook has them, such as the Everlong hook's whole tuning row with `setTuning(Tuning)` A pool may also have a controller hook. This hook orders the pool's lending markets for certain operations, and can call `maintain` and recentre the anchor. The LTV pin is the loan-to-value ceiling a borrowing pool holds itself to. The credit setting is how much a sell's incoming pool asset counts towards what such a pool can borrow. One `setDials` call sets both. [Credit and collateral](/how-pools-work/credit-and-collateral.md) gives the rules on each move. A hook's keeper settings stay inside the pool operator's bounds and the limits fixed in the hook's code. [The Everlong strategy](https://docs.foreverlong.io/everlong/everlong-strategy) lists the Everlong hook's settings and their limits. ### Guardian The pool operator appoints the guardian. The guardian can: * pause the pool, the entry market and tranches * cancel scheduled hook sets, venues and loan assets, and a scheduled raise in the price band or fee cap ceiling * tighten limits, caps, venue flags, the oracle band and feature switches, but never loosen them * attach a price band to a pool that has none with `setMarketBand`, but never drop a band * switch off the pool-asset reserve, but never set one * use the same emergency calls as the pool operator ### Protocol Safe The protocol Safe acts on what every pool shares. It can: * schedule new pool code for every pool * bind a new venue type, or replace the account deployer that deploys pools' accounts for an existing type * cancel a scheduled upgrade or venue type * set each pool's protocol performance fee, the rate new pools start at and the address that receives it * pause new borrowing and supply on the shared financing router New code, new venue types and rises in a protocol fee wait for the factory's delay. After that, anyone can execute them. A cut applies at once. No protocol fee can exceed 50%. The price feed contract a pool reads has a Safe of its own. In the first deployment, that's the protocol Safe. The price feed's Safe lists tokens and replaces a listed token's price source, staleness limit and peg band. See [Price feeds and oracles](/how-pools-work/price-feeds-and-oracles.md). ### Calls open to anyone Any address, with no role at all, can: * swap * redeem shares it holds or is approved to spend * deposit, if the pool's deposit allowlist admits the address receiving the shares * record a new price observation with `poke()` on the pool, in a pool with a price band * top up collateral with `maintainCollateral()` on the pool, in a pool that owes debt at a lending market. The call acts at the least healthy eligible venue. A venue is eligible once its LTV has used a fifth of the room from the LTV pin to its liquidation LTV. * mark each loan asset the pool no longer owes as debt-free with `proveDebtFree()` on the pool * charge the performance fee with `skimPerformanceFee()` on the pool. [Fees](/use-efficient/fees.md) explains how. * execute a due performance fee rise with `executePerformanceFee()` on the pool * execute a due protocol fee rise with `executeProtocolFee(pool)` or `executeDefaultProtocolFee()` on the factory * execute a scheduled upgrade or venue type once its delay has passed, with `executeImplementation()` or `executeAccountDeployer(kind)` on the factory * execute a due price source replacement with `executeOracle(token)` on the price feed * fill, net or crank requests on the entry market * settle junior tranche requests with `settleForward(id)` on the tranche controller * create pools ### What tightening means **The contracts check every guardian change against the current setting.** A call that would loosen anything reverts with `GuardianMayOnlyTighten`. Tightening means any of these: * a lower cap or rate ceiling * a narrower price band or oracle band * a higher fee floor on a loan asset * a larger reserve target for a loan asset's execution buffer * a larger supply batch * fewer loan assets carrying debt at once * switching off a venue flag, a feature or a loan asset's borrowing * switching on the oracle band or the fund re-check * attaching a price band to a pool that has none * switching off the pool-asset reserve, which is the guardian's only move on that rule Only the pool operator can change the pool-wide fee bounds or the hooks' owner settings, or drop a price band. The same goes for the price band and fee cap ceilings, though the guardian can cancel a scheduled raise. [Just-in-time financing](/how-pools-work/just-in-time-financing.md) explains the execution buffer and the supply batch. [Credit and collateral](/how-pools-work/credit-and-collateral.md) covers the oracle band and the fund re-check. Zero means no cap for the debt cap, the supply cap, the rate ceiling and the per-swap cap. So the guardian can't set any of them to zero. A zero cap on `mintProRata`, the share-sized entry, closes that entry instead. The pool sets no deposit cap of its own. The guardian can always close deposits by switching off bit 0 or pausing the pool. Exits from a pool that borrows can be waiting on a buy that repays a lending market whose oracle has stopped. Some tightening restricts that buy. Switching off buys, a narrower price band or a fee floor above the hook's quoted fee can each block it. A lower per-swap cap can cut it short of the debt. A pause can't stop it, because buys continue during a pause. ### Emergency calls A pool with lending markets has four emergency calls, through `emergency(kind, id, assets)`. The pool operator and the guardian share them. Each acts on one venue, and only reduces risk or returns assets to the pool. No pause or feature switch stops them. [Credit and collateral](/how-pools-work/credit-and-collateral.md#emergency-calls) covers each one. ## Pausing **A pause stops what adds risk and leaves open what reduces it.** The pool operator or the guardian can pause a pool with `setPaused(true)`. Only the pool operator can unpause it. A creator can also create a pool paused. The pool operator's unpause is then the pool's first risk-adding step. [Configure a pool](/run-a-pool/configure-a-pool.md#activating-the-pool) covers that activation. | Stops during a pause | Continues during a pause | | --------------------------------------------------- | ---------------------------------------------------- | | Sells, including the Everlong hook's lever-up fills | Buys, including the Everlong hook's lever-down fills | | Deposits | Redemptions | | New price observations | Collateral top-ups | | Anchor moves | Keeper maintenance | | Loan-to-loan swaps | Emergency calls | | Lending a buy's surplus | Repaying debt with a buy | Executing a new hook set needs the pool paused. So does reshaping the Everlong hook's curve. [Trade](/use-efficient/trade.md) covers the other conditions that block or reduce trading. ### Other pauses The financing router, the entry market and tranches each have a pause of their own. The entry market takes requests to enter or exit. Tranches split a pool's shares into senior and junior claims. | Pause | Who can pause | Who can unpause | What it stops | | -------------------- | ------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | The pool | Pool operator or guardian | Pool operator | The left column above | | The financing router | Protocol Safe | Protocol Safe | New borrowing and supply for every pool, deposits that would borrow or supply, and moves between venues. Sells fill only from the loan asset the pool holds or can withdraw from what it has supplied. | | The entry market | Pool operator or guardian | Pool operator | New requests. Existing requests can still fill or be cancelled. | | Tranches | Pool operator or guardian | Pool operator | Tranche entries, including the settlement of junior entry requests already posted. Exits continue. | [Provide liquidity](/use-efficient/provide-liquidity.md) covers the entry market. [Tranches](/use-efficient/provide-liquidity/tranches.md) covers the tranche controller. ### Feature switches Feature switches are separate from the pause. The pool operator sets the whole bitmap with `setFeatures(bitmap)`. The guardian can only clear bits. | Bit | Value | Switches on | | --- | ----- | ------------------------------------------------------------------------------------- | | 0 | 1 | Deposits | | 1 | 2 | Sells | | 2 | 4 | Buys | | 3 | 8 | Lending a buy's surplus to venues | | 4 | 16 | Keeper maintenance through `maintain` | | 5 | 32 | Lever-up fills, for an invariant hook with a leverage curve such as the Everlong hook | | 6 | 64 | Loan-to-loan swaps through `swapLoan` | Executing a hook set that changes the invariant hook clears bit 5. The new hook then quotes no leverage fill until the pool operator sets the bit again. [The Everlong strategy](https://docs.foreverlong.io/everlong/everlong-strategy) explains how bit 5 arms the Everlong hook. The buy switch stops buys, which a pause never does. No pause or feature switch stops redemptions, the permissionless collateral top-up or the emergency calls. ## Changes and notice **Some changes wait for a delay before they take effect.** Delays apply to new pool code, hooks, venue types, venues and loan assets. They also apply to performance fee rises, ceiling raises and replacement price sources. The Notice column shows how much warning comes before each change takes effect. A change with no notice takes effect in the transaction that makes it. | Change | Who | Notice | Conditions | | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | New hooks: the three required hooks (curve, fee and recentring) and the optional controller and loan-to-loan swap hooks | Pool operator | The pool's governance delay, at least one day | Executes only while the pool is paused. The pool operator or guardian can cancel. The set waits at least 10 days while the band ceiling allows no price band, or while a raise to allow none is scheduled | | A new venue | Pool operator | The same delay | Up to 32 per pool. A pool with no price band admits only a venue with borrowing off. The pool operator or guardian can cancel | | A new loan asset | Pool operator | The same delay | Up to 16 per pool. The pool's price feed must be able to price each one. A pool with no price band takes no second loan asset. The pool operator or guardian can cancel | | A rise in the pool operator's performance fee | Pool operator | The same delay | Anyone executes it once due. Only the pool operator can cancel it, by setting the current rate or a lower one. The rate can't exceed a ceiling fixed at creation, which is at most 50%. A pool with no price band takes no rise | | A raise in the price band's or the fee cap's ceiling | Pool operator | The same delay, and at least 10 days for the band's | The pool operator applies it once due by repeating the call. The pool operator or the guardian can cancel it. A ceiling that allows no price band lets the pool operator drop the band. See [Hooks](/how-pools-work/hooks.md) | | New pool code | Protocol Safe | The factory's delay, at least one day | The new code must report a higher version. Anyone can execute it after the delay, and every pool moves to the new code at once. The protocol Safe can cancel | | A new or replaced venue type | Protocol Safe | The factory's delay | Anyone can execute it after the delay. The protocol Safe can cancel. Accounts already deployed keep their code. An existing pool uses a replacement only when a delayed `addVenue` deploys it a new account | | A rise in a pool's protocol performance fee, or in the rate new pools start at | Protocol Safe | The factory's delay | Anyone executes it once due. Never above 50%. The protocol Safe can cancel. A pool's rise can't land while it has no price band | | A new price source, staleness limit or peg band for a token on the price feed | The price feed's Safe | 10 days, or 4 hours while the token's feed is failing | Anyone executes it once due. The Safe can cancel | | Risk limits, caps, the rate ceiling, the oracle band, the fund re-check, the supply batch, venue flags and feature switches | Pool operator, or the guardian to tighten only | None | The price band can't exceed 10% or its ceiling. The oracle band can't exceed 20% | | Dropping the price band with `setMarketBand`, or attaching one to a pool that has none | Pool operator, or the guardian to attach only | None | Dropping needs a band ceiling that allows no band, no debt, borrowing off, one loan asset and an invariant hook that prices without a feed price | | The pool-asset reserve, set with `setPoolAssetReserve` | Pool operator, or the guardian to switch it off only | None | Only at a lending market that pays a return on collateral. Morpho Blue doesn't, so the rule is off on every pool today | | Fee bounds, a cut in the performance fee or in either ceiling, the deposit allowlist, and the keeper, guardian and fee receiver | Pool operator | None | The fee cap can't exceed its ceiling | | The hooks' owner settings, such as the Everlong hook's bounds and curve shape | Pool operator | None | The Everlong hook reshapes its curve only while the pool is paused. Reshapes move its quoted price by at most 1% in total between two anchor moves | | The DEX routers the asset router converts through | Pool operator | None | | | The largest discount an entry-market request can set | Pool operator | None | Never above 10% | | Retiring a venue or a loan asset | Pool operator | None | A venue only once it holds nothing, and not the pool-asset reserve's venue while that rule is on. A loan asset only once every venue of it is retired and empty. Retiring a loan asset is permanent | | Handing over the pool operator role | Pool operator | None | The new pool operator must accept | | The hooks' keeper settings, the LTV pin and the credit setting | Keeper or pool operator | None | Within bounds set by the pool operator, at creation or in the hook's code | | The senior tranche's target rate | Keeper or pool operator | None | Anywhere inside the range fixed when the tranches were created | | Venue order, collateral top-ups and releases, and moving debt or the supplied loan asset between venues | Keeper, pool operator or the pool's controller hook | None | Everything except venue order needs the maintenance switch on | | Emergency repay, top-up or withdrawal on a venue | Pool operator or guardian | None | | | Pausing the pool, the entry market or tranches | Pool operator or guardian | None | Only the pool operator can unpause | | Pausing new borrowing and supply on the financing router | Protocol Safe | None | Affects every pool, because the router is shared | | The protocol fee receiver | Protocol Safe | None | Never the zero address | | Listing a new token on the price feed | The price feed's Safe | None | A pool uses it only once its pool operator adds it as a loan asset, after the pool's delay | The pool's governance delay applies to new hooks, new venues, new loan assets and rises in the pool operator's performance fee. Each changes what the pool relies on or charges: * new hooks change its pricing * a new venue adds a lender and its oracle * a new loan asset adds an asset it can owe * a fee rise changes its fee A raise in the price band's or fee cap's ceiling waits for the same delay, and at least 10 days for the band's. In the first Everlong vault, the pool's governance delay and the factory's delay are both 10 days. [The Everlong strategy](https://docs.foreverlong.io/everlong/everlong-strategy) lists the rest of its configuration, including who holds each role. [Fees](/use-efficient/fees.md) explains how a change to either performance fee rate lands. It also explains why an uncharged gain never meets a higher rate. ### Making a delayed change A new venue or loan asset uses the same call twice: 1. The pool operator calls `addVenue(v)` or `addLoanAsset(token, bandWad, feeFloorWad, maxSwapNotional, reserveTarget)` with the exact parameters. This schedules the change and starts the pool's governance delay. 2. After the delay, the pool operator repeats the identical call to execute it. A pool holds one scheduled venue and one scheduled loan asset at a time. A call with different parameters replaces it and restarts the delay. The pool operator or the guardian can cancel the change before it executes. To cancel, they call `addVenue` with empty venue parameters, or `addLoanAsset` with a zero token address. A new hook set takes more steps: 1. The pool operator calls `scheduleHookSet(hookSet)`, which starts the pool's governance delay. Scheduling another set replaces it and restarts the delay. 2. The delay runs. The pool operator or the guardian can call `cancelHookSet()` in the meantime. 3. The pool operator pauses the pool with `setPaused(true)`. Buys still fill during a pause. So if the set changes the invariant hook, the pool operator should also clear the buy switch, bit 2, with `setFeatures`. 4. The pool operator calls `executeHookSet(hookSet)` with the exact set it scheduled. A new invariant hook starts from its own book and anchor. Executing a set that changes the invariant hook clears bit 5. 5. The pool operator unpauses the pool with `setPaused(false)`. If the set changed the invariant hook, the keeper then recentres the new hook. Until that first recentre, a new Everlong hook prices from the anchor it was built with. 6. If step 3 cleared bit 2, the pool operator sets it again with `setFeatures` to reopen buys. With the Everlong hook, it first waits until the new hook's `levState` matches the old hook's reading. Then it sets bits 2 and 5 together. ### Seeing a delayed change coming **Delayed changes are scheduled onchain before they take effect, so depositors can see them coming.** Each scheduling call emits an event. The event gives the time the change can execute. * On the pool, `pendingHookSet()` returns a hash of the pending hook set and the time it can execute. It also returns a hash of the pending venue's parameters and its time. The `HookSetScheduled` event carries the full hook set. * The venue hash doesn't say which lending market is proposed. The input of the scheduling transaction shows it. The `VenueScheduled` event gives its venue type and the index of its loan asset. * A pending loan asset has no read function. The signal to watch is the `LoanAssetScheduled` event, which names the token and the time it can execute. * `limits()` on the pool returns a pending performance fee rise and the time it can execute. The `PerformanceFeeScheduled` event announces it too. * `ceilings()` on the pool returns the price band and fee cap ceilings, any pending raise and the time it can execute. The `CeilingsScheduled` event announces a raise too. * On the factory, `pendingImplementation()` and `implementationExecutableAt()` show pending code. `pendingAccountDeployer(kind)` and `accountDeployerExecutableAt(kind)` show a pending venue type. `pendingProtocolFee(pool)` and `pendingDefaultProtocolFee()` show a pending protocol fee rise. * On the price feed, `pendingOracle(token)` shows a pending replacement of a token's price source. ### New pool code The factory records the new code's hash when the change is scheduled. It refuses to execute the change if the code at that address has changed since. That locks in the bytecode that reviewers can read during the delay. The hash check doesn't stop the new code loading logic from another contract when it runs. The hash can't show whether it does, either. So a review still has to confirm that the new code doesn't. [Security and audits](/reference/security-and-audits.md) lists what has been reviewed so far. ## Fixed at creation **The pool writes some settings once, at creation, and no pool role can change them afterwards:** * the pool asset and the first loan asset * the price feed contract the pool reads, though not the price sources its Safe manages * the authority contract that records the roles, though the pool operator still manages the roles * the deposit allowlist contract, though the pool operator still manages who's on the allowlist * the financing router * the pool's governance delay * the limits on the LTV pin and the credit setting * the largest single rise of the LTV pin, and the cooldown between moves * the gap the LTV pin must keep below the liquidation LTV of every venue the pool can borrow from or still owes * the age limit that loan-to-loan swaps apply to both prices * the performance fee ceiling New pool code can still change the settings the pool stores, including which price feed it reads. The protocol Safe schedules new code with the factory's delay. The factory, the financing router and the price feed contract can't be upgraded. The protocol Safe and the factory's delay are fixed when the factory is deployed. ## Factory provenance **The factory records where each pool came from.** Anyone can create a pool through it. Its `PoolCreated` event names the creator and the invariant hook with its code hash. It also carries hashes of the hook set and the risk settings. The hook set's hash commits to all five hook slots at creation. The pool's `HooksSet` event lists them in the same transaction. The lens's `identity(pool)` returns the same five slots until a hook change. The factory checks no hooks itself. [Hooks](/how-pools-work/hooks.md) gives the checks the pool runs. Neither the factory nor the pool checks anything else about a hook. A depositor can read a factory pool's governance onchain before depositing: * `isPool(pool)` on the factory to confirm it created the pool, `pools()` for every pool it created, and the `PoolCreated` event for the creator * `hooks()` for the hooks the pool runs now, and `pendingHookSet()` for any scheduled change * `core()` for its authority contract, then `owner()`, `guardian()`, `keeper()` and `feeReceiver()` on that contract * `paused()` for the pool pause, and `switches()` for its feature switches and its governance delay * `limits()` for its fee bounds, both performance fee rates, the performance fee ceiling and the cap on `mintProRata` * `ceilings()` for the ceilings on its price band and fee cap * `loanConfig(i)` for each loan asset's price band, fee floor, per-swap cap and reserve target * `dials()` for the LTV pin, the credit setting and their limits * `pin(pool)` and `fundRecheck(pool)` on the financing router for the oracle band and the fund re-check * `depositAllowlist()` for its allowlist contract, then `enabled()` and `isDepositAllowed(address)` on that contract The factory doesn't check that a pool's authority contract, allowlist contract or price feed contract is the standard one. The standard authority contract provides the two-step handover, the pool operator role that can't be renounced and the fee receiver that's never empty. The pool operator manages the allowlist only when the allowlist contract points back at the pool's authority contract. If a pool uses other contracts in any of these places, a depositor should check their code before depositing. [Smart contracts](/reference/smart-contracts.md) lists the contracts, the `PoolCreated` fields and the lens views that read these settings.