Leverage: Overview
Llamalend v2 markets support leveraged positions: a user deposits some collateral, borrows the market's borrowed token, swaps the borrowed amount into more collateral and adds it to the same loan, all in one transaction. Deleveraging works the other way round. Part of the position's collateral is sold for the borrowed token, and the proceeds repay debt.
The swap is done by a leverage zap, a helper contract that the controller calls back during create_loan, borrow_more and repay. The zap routes the swap through a whitelisted exchange: the Curve router or an aggregator router such as 0x, Enso or KyberSwap.
There are two leverage zaps for Llamalend v2: the newer TransientLeverageZap and the original LeverageZap. This page explains how they differ, how the TransientLeverageZap works and what integrators need to set up. Function-level documentation is on each zap's reference page.
Deployments
| Contract | Ethereum | Optimism |
|---|---|---|
| TransientLeverageZap | 0xFE02…9AE2 | 0xA7a4…299B |
| LeverageZap | 0x5D84…b85 | 0xdbeB…584a |
Each zap is bound to the Llamalend v2 LendFactory on its chain and only works with markets deployed by that factory.
LeverageZap vs. TransientLeverageZap
Both zaps produce the same result. They differ in who calls the controller and how the swap route reaches the zap.
| LeverageZap | TransientLeverageZap | |
|---|---|---|
| Entry point | The user calls the controller, passing the zap as the callback target | The user calls the zap, which calls the controller on their behalf |
| How the swap route reaches the zap | ABI-encoded in the controller's callback calldata | Stored in the zap's transient storage for the duration of the call |
| Maximum swap route size | Limited by the controller's CALLDATA_MAX_SIZE (9,600 bytes, minus the encoded parameters) | 32,000 bytes |
| Controller approval needed | No | Yes: controller.approve(zap, True) |
| Exchange spending cap | None; the exchange is approved for max_value(uint256) during the swap | The borrowed amount (_debt) or _collateral_to_spend |
max_borrowable | Uses loan_discount only | Also applies the user's extra_health and checks _N |
Aggregator routes regularly exceed the controller's calldata limit, which is why the TransientLeverageZap exists. The price is one extra approval: since the zap creates, extends and repays loans for the user, the user has to allow it to act for them on the controller.
How the TransientLeverageZap Works
Every entry point of the TransientLeverageZap (create_loan, borrow_more, repay) follows the same pattern:
- Resolve the market. The caller passes a market index (
_controller_id), and the zap looks up the controller withLendFactory.markets(_controller_id).controller. - Pull the user's funds. The zap transfers collateral (for
create_loanandborrow_more) or borrowed tokens (forrepay) from the caller to itself. It has to hold them because the controller pulls them from itsmsg.sender, which is the zap. - Stash. The swap parameters (
_exchange_address,_exchange_calldata, the spend cap and_min_recv) and the zap's current token balance are written to transient storage. While a call is in progress, the stored controller address also blocks reentry into the entry points. - Call the controller on behalf of
msg.sender, with the zap as the callback target and empty callbackcalldata. - Callback. The controller calls
callback_depositorcallback_repayon the zap. The zap checks that the caller is the controller it is currently calling, approves the exchange for at most the spend cap, executes the swap viaraw_call, revokes the approval, checks slippage and returns the amounts to the controller. - Unstash and refund. After the controller call returns, the transient values are cleared and all borrowed and collateral tokens left in the zap are sent back to the caller.
Slippage and spending limits
The zap protects the user in three ways during the swap:
- Output check: the swap must return at least
_min_recv(collateral when leveraging, borrowed token when deleveraging), otherwise the transaction reverts with"Slippage". - Input cap: the exchange is approved for at most
_debtborrowed tokens when leveraging, or_collateral_to_spendcollateral when deleveraging. The approval is revoked right after the swap. - Funds already in the zap are excluded: the swap output is measured against the zap's balance before the swap, so tokens the user parked in the zap for the controller can never be counted as swap proceeds.
Integration
Using the TransientLeverageZap
Before calling any entry point of the TransientLeverageZap, the user must:
- call
approve(zap, True)on the market's LendController, so the zap may create, extend or repay a loan for them; - approve the zap to spend the collateral token (for
create_loanandborrow_more) or the borrowed token (forrepay, when_wallet_d_debt > 0).
A typical flow to open a leveraged position:
- Pick a market. Get its index in the
LendFactoryand its controller address. - Get a swap route. Request a route from the Curve router or an aggregator for swapping the amount you plan to borrow into collateral. The route must use a whitelisted exchange (see below) and must send its output to the zap, because the zap measures its own balance after the swap. Set the zap as the taker/sender of the swap as well, since the zap holds the borrowed tokens.
- Check the borrow limit. Call
max_borrowablewith the user's collateral, the collateral expected from the swap, the number of bands and the swap's average price. Borrow no more than the returned amount. - Approve. Approve the zap on the controller and on the collateral token (see prerequisites).
- Open the position. Call
create_loanwith the market index, collateral, debt, number of bands, the minimum collateral to receive, the exchange address and the route calldata.
Increasing leverage (borrow_more) works the same way. To deleverage or close a position, request a route that swaps collateral into the borrowed token and call repay. Pass max_value(uint256) as _wallet_d_debt to cover any shortfall from the wallet when closing the position completely.
Using the LeverageZap
With the LeverageZap, the user calls the controller directly and passes the zap as _callbacker. The swap parameters go into the controller's _calldata, ABI-encoded as (controller_id, min_recv, exchange_address, exchange_calldata). No approval of the zap on the controller is needed. See Using the Zap for the encoding and the matching controller calls.
Exchange Whitelist
Each zap only calls exchanges on its own whitelist. The whitelists are managed by the admin of the LendFactory through set_exchange. Use is_approved_exchange to check the current state. To disable a zap entirely, the admin can remove every exchange from its whitelist.
TransientLeverageZap
The following exchanges were added at deployment:
| Exchange | ||
|---|---|---|
| Curve Router | 0x4531…cd4e | 0x0DCD…d983 |
CurveRouterV2.vy | 0xa1C7…cb5 | — |
| Enso Router V2 | 0xF755…22Cf | 0xF755…22Cf |
| 0x Allowance Holder | 0x0000…2734 | 0x0000…2734 |
| KyberSwap Meta Aggregation Router v2 | 0x6131…37b5 | 0x6131…37b5 |
LeverageZap
On Ethereum, the zap was deployed with four exchanges. Odos has since been removed from the whitelist:
| Exchange | Address | Approved |
|---|---|---|
| Curve Router | 0x4531…cd4e | Yes |
CurveRouterV2.vy | 0xa1C7…cb5 | Yes |
| Enso Router V2 | 0xF755…22Cf | Yes |
| Odos Router V3 | 0x0D05…0D05 | No (removed) |