Hooks

Learn how Lotus hooks execute custom validation logic after supply, borrow, and withdraw operations, including AllowlistHook and BorrowHealthGuardHook.

Hooks are the protocol's extension points. After certain operations — supply, borrow, withdraw, collateral supply, and collateral withdrawal — Lotus can call a designated hook contract to execute custom logic. Hooks enable market operators to enforce rules that go beyond the core protocol, for example restricting who can interact with a market or enforcing stricter health requirements on borrowers.

Hooks are configured per-market by the admin using setMarketHook. Each hook is an external contract that implements the ILotusHooks interface. The admin specifies which operations trigger the hook via a permissions bitmask, so a hook that only needs to enforce rules on borrows does not add gas cost to supply or withdraw operations.

When Hooks Fire

Hooks execute after the core operation's state changes complete but before the token transfer. For example, when a lender supplies to a market with an active supply hook, Lotus first performs the supply (accrual, share minting) and then calls the hook's afterSupply method. If the hook reverts, the entire transaction reverts — giving the hook veto power over the operation.

sequenceDiagram
    participant User
    participant Lotus
    participant Hook

    User->>Lotus: supply()
    Lotus->>Lotus: Accrue interest, mint shares
    Lotus->>Hook: afterSupply(SupplyParams)
    Hook->>Hook: Custom logic (e.g. check allowlist)
    Hook-->>Lotus: Return selector (success)
    Lotus->>Lotus: Transfer tokens
    Lotus-->>User: Return (assets, shares)

A revert at any point — including inside the hook — rolls back the entire transaction.

Available Hook Points

Five hook points exist, each corresponding to a core operation. afterSupply fires after a lender supplies loan tokens to a tranche. afterBorrow fires after a borrower takes a loan from a tranche. afterSupplyCollateral fires after a borrower deposits collateral. afterWithdraw fires after a lender withdraws supply from a tranche. afterWithdrawCollateral fires after a borrower withdraws collateral.

Each hook receives a parameter struct containing the operation's details: market ID, tranche index, sender, on-behalf address, and the assets and shares involved. The hook can inspect these parameters to make its decision.

Hooks are "after" hooks — they cannot modify the operation, only approve or reject it. A hook approves by returning its own function selector; it rejects by reverting. Because hooks are invoked via staticcall, they cannot modify state.

Production Hooks

Two hooks ship with the protocol. The AllowlistHook restricts market access to whitelisted addresses. The market operator can allowlist specific senders and on-behalf addresses per tranche. Any operation from a non-allowed address is reverted. The allowlist is checked on all five hook points, giving the operator full control over who can interact with the market.

The BorrowHealthGuardHook enforces a stricter health requirement on borrowers. The operator sets a health factor per tranche as a fraction of the protocol's liquidation loan-to-value (LLTV). After a borrow, the hook verifies that the borrower's position does not exceed the tightened limit — effectively creating a buffer zone above the LLTV. For example, setting a factor of 0.9 (0.9e18) on a tranche with 90% LLTV means borrowers can only borrow up to 81% LTV through that hook's enforcement. This hook only fires on borrows, leaving supply and collateral operations unaffected.

How Hooks Are Configured

The Lotus admin configures hooks using setMarketHook (see Admin reference). The admin specifies the hook contract address and a permissions bitmask indicating which operations trigger the hook. To remove a hook, the admin sets the address to the zero address with zero permissions. If the hook contract does not contain code at the time of configuration, the transaction reverts.

See Also

• Reference → Hooks for the full API

• Build → Hooks for implementation guide

• Reference → Admin for setMarketHook documentation