Hooks

API reference for the Lotus hooks system covering ILotusHooks interface, permission flags, AllowlistHook, and BorrowHealthGuardHook parameters.

The hooks system consists of the ILotusHooks interface (which hook contracts implement), the Hooks.sol library (which the core protocol uses to manage and invoke hooks), and two production implementations: AllowlistHook and BorrowHealthGuardHook.

ILotusHooks Interface

All hooks are invoked via staticcall. Each method must return its own function selector (bytes4) on success. Any revert causes the parent operation to revert.

Hooks are invoked via staticcall and cannot modify state. A hook that reverts on every call will lock users out of all hooked operations on that market.

---

afterSupply

function afterSupply(SupplyParams calldata params) external view returns (bytes4);

Called after supply state changes, before token transfer.

SupplyParams

| Field | Type | Description | |||***| | id | Id | Market identifier | | trancheIndex | uint256 | Tranche being supplied to | | sender | address | Address that initiated the supply call | | onBehalf | address | Address credited with supply shares | | assets | uint256 | Amount of loan tokens supplied | | shares | uint256 | Amount of supply shares minted |

---

afterBorrow

function afterBorrow(BorrowParams calldata params) external view returns (bytes4);

Called after borrow state changes and health checks, before token transfer.

BorrowParams

| Field | Type | Description | |||***| | id | Id | Market identifier | | trancheIndex | uint256 | Tranche being borrowed from | | sender | address | Address that initiated the borrow call | | onBehalf | address | Address whose position is debited | | receiver | address | Address receiving the borrowed tokens | | assets | uint256 | Amount of loan tokens borrowed | | shares | uint256 | Amount of borrow shares created |

---

afterSupplyCollateral

function afterSupplyCollateral(SupplyCollateralParams calldata params) external view returns (bytes4);

Called after collateral supply state changes, before token transfer.

SupplyCollateralParams

| Field | Type | Description | |||***| | id | Id | Market identifier | | trancheIndex | uint256 | Tranche receiving collateral | | sender | address | Address that initiated the collateral supply | | onBehalf | address | Address credited with the collateral | | assets | uint256 | Amount of collateral tokens deposited |

---

afterWithdraw

function afterWithdraw(WithdrawParams calldata params) external view returns (bytes4);

Called after withdrawal state changes, before token transfer.

WithdrawParams

| Field | Type | Description | |||***| | id | Id | Market identifier | | trancheIndex | uint256 | Tranche being withdrawn from | | sender | address | Address that initiated the withdrawal | | onBehalf | address | Address whose supply shares are burned | | receiver | address | Address receiving the withdrawn tokens | | assets | uint256 | Amount of loan tokens withdrawn | | shares | uint256 | Amount of supply shares burned | | shouldAccrueInterest | bool | Whether interest was accrued before withdrawal |

---

afterWithdrawCollateral

function afterWithdrawCollateral(WithdrawCollateralParams calldata params) external view returns (bytes4);

Called after collateral withdrawal state changes, before token transfer.

WithdrawCollateralParams

| Field | Type | Description | |||***| | id | Id | Market identifier | | trancheIndex | uint256 | Tranche from which collateral is withdrawn | | sender | address | Address that initiated the collateral withdrawal | | onBehalf | address | Address whose collateral is being withdrawn | | receiver | address | Address receiving the collateral tokens | | assets | uint256 | Amount of collateral tokens withdrawn |

---

Hooks Library

The Hooks.sol library provides permission flags, configuration validation, and the internal call mechanism used by Lotus core.

Permission Flags

| Flag | Value | Triggers On | |||***| | AFTER_SUPPLY_FLAG | 1 << 0 (1) | supply() | | AFTER_BORROW_FLAG | 1 << 1 (2) | borrow() | | AFTER_SUPPLY_COLLATERAL_FLAG | 1 << 2 (4) | supplyCollateral() | | AFTER_WITHDRAW_FLAG | 1 << 3 (8) | withdraw() | | AFTER_WITHDRAW_COLLATERAL_FLAG | 1 << 4 (16) | withdrawCollateral() |

Combine flags with bitwise OR. For example, a hook that fires on both supply and borrow uses AFTER_SUPPLY_FLAG | AFTER_BORROW_FLAG (3).

HookConfig

struct HookConfig {
    address hook;
    uint256 permissions;
}

Stored per-market. The hook address is the deployed hook contract; permissions is the bitmask of active flags.

validateHookConfig

function validateHookConfig(address hook, uint256 permissions) internal view returns (HookConfig memory);

Validates a hook configuration. If hook is the zero address, returns an empty config (hooks disabled). If hook is non-zero but contains no code, reverts with InvalidHook(hook).

hasPermission

function hasPermission(uint256 permissions, uint256 flag) internal pure returns (bool);

Returns true if the given flag is set in the permissions bitmask.

Errors

| Error | When | ||| | HookCallFailed(address hook, bytes4 selector) | The hook's staticcall reverted | | InvalidHookResponse(address hook, bytes4 expected, bytes4 received) | The hook returned an unexpected selector | | InvalidHook(address hook) | The hook address has no deployed code |

---

AllowlistHook

Restricts market operations to whitelisted addresses. Checks both the transaction sender and the on-behalf address on all five hook points.

Storage

mapping(Id => mapping(uint256 => mapping(address => bool))) public isSenderAllowed;
mapping(Id => mapping(uint256 => mapping(address => bool))) public isOnBehalfAllowed;

constructor

constructor(address _owner)

| Parameter | Type | Description | Required | ||||| | _owner | address | Initial owner of the hook | Yes |

Reverts: ZeroAddress() if _owner is the zero address.

setOwner

function setOwner(address newOwner) external;

| Parameter | Type | Description | Required | ||||| | newOwner | address | New owner address | Yes |

Reverts: NotOwner() if caller is not the current owner. ZeroAddress() if newOwner is the zero address.

setSenderAllowed

function setSenderAllowed(Id id, uint256 trancheIndex, address who, bool allowed) external;

| Parameter | Type | Description | Required | ||||| | id | Id | Market identifier | Yes | | trancheIndex | uint256 | Tranche index | Yes | | who | address | Address to allow or disallow as sender | Yes | | allowed | bool | Whether the address is allowed | Yes |

Reverts: NotOwner() if caller is not the current owner.

setOnBehalfAllowed

function setOnBehalfAllowed(Id id, uint256 trancheIndex, address who, bool allowed) external;

| Parameter | Type | Description | Required | ||||| | id | Id | Market identifier | Yes | | trancheIndex | uint256 | Tranche index | Yes | | who | address | Address to allow or disallow as on-behalf target | Yes | | allowed | bool | Whether the address is allowed | Yes |

Reverts: NotOwner() if caller is not the current owner.

Hook Behavior

All five hook methods (afterSupply, afterBorrow, afterSupplyCollateral, afterWithdraw, afterWithdrawCollateral) perform the same check:

1. Verify isSenderAllowed[id][trancheIndex][sender] is true. Reverts with SenderNotAllowed(sender) otherwise.

2. Verify isOnBehalfAllowed[id][trancheIndex][onBehalf] is true. Reverts with OnBehalfNotAllowed(onBehalf) otherwise.

Errors

| Error | When | ||| | SenderNotAllowed(address sender) | Sender is not on the allowlist for this market/tranche | | OnBehalfNotAllowed(address onBehalf) | On-behalf address is not on the allowlist for this market/tranche | | NotOwner() | Caller is not the hook owner | | ZeroAddress() | Zero address provided where non-zero is required |

---

BorrowHealthGuardHook

Enforces a stricter health requirement on borrowers by applying a multiplier (factor) to the protocol's LLTV. Only hooks into afterBorrow; all other hook points use the default pass-through from BaseLotusHook.

Storage

ILotus public immutable lotus;
mapping(Id => mapping(uint256 => uint256)) public factor;

The factor is in WAD format (1e18 = 100%). A factor of 0.9e18 means the borrower can only borrow up to 90% of the protocol maximum.

constructor

constructor(address _owner, ILotus _lotus)

| Parameter | Type | Description | Required | ||||| | _owner | address | Initial owner of the hook | Yes | | _lotus | ILotus | Address of the Lotus core contract | Yes |

Reverts: ZeroAddress() if either parameter is the zero address.

setOwner

function setOwner(address newOwner) external;

| Parameter | Type | Description | Required | ||||| | newOwner | address | New owner address | Yes |

Reverts: NotOwner() if caller is not the current owner. ZeroAddress() if newOwner is the zero address.

setFactor

function setFactor(Id id, uint256 trancheIndex, uint256 newFactor) external;

| Parameter | Type | Description | Required | ||||| | id | Id | Market identifier | Yes | | trancheIndex | uint256 | Tranche index | Yes | | newFactor | uint256 | Health factor multiplier in WAD (must be ≤ 1e18) | Yes |

Reverts: NotOwner() if caller is not the current owner. InvalidFactor(newFactor) if newFactor > 1e18.

A factor of 0 means the guard is not configured for that tranche (no check performed). Setting a factor effectively tightens the borrowing limit: strictMaxBorrow = protocolMaxBorrow * factor / WAD.

afterBorrow Behavior

1. Load the factor for the market and tranche. If zero, return immediately (unconfigured).

2. Fetch market parameters, tranche state, and borrower position from Lotus.

3. Convert the borrower's borrow shares to assets: borrowed = borrowShares.toAssetsUp(trancheBorrowAssets, trancheBorrowShares).

4. Compute the protocol maximum borrow: protocolMaxBorrow = collateral * oraclePrice / ORACLE_PRICE_SCALE * LLTV / WAD.

5. Apply the factor: strictMaxBorrow = protocolMaxBorrow * factor / WAD.

6. If borrowed > strictMaxBorrow, revert with HealthFactorTooLow(borrowed, strictMaxBorrow).

Errors

| Error | When | ||| | HealthFactorTooLow(uint256 borrowed, uint256 maxAllowed) | Borrow exceeds the guard-adjusted maximum | | InvalidFactor(uint256 factor) | Factor exceeds 1e18 | | NotOwner() | Caller is not the hook owner | | ZeroAddress() | Zero address provided in constructor |

---

See Also

• Learn → Hooks for conceptual explanation

• Build → Hooks for implementation guide

• Reference → Admin for setMarketHook documentation