# Gearbox Protocol documentation full export > Full text export for agents and retrieval systems. Use https://docs.gearbox.finance/llms.txt for compact routing before loading this file. Source hierarchy and freshness rules: - Static documentation describes protocol mechanics, integration patterns, and operational procedures. - Mutable market facts such as APY, utilization, market availability, supported assets, supported chains, rates, addresses, or live incidents must be verified through Gearbox app, Gearbox Data, governance, security, deployment, or owner-reviewed sources before answering. - Legal, tax, investment, eligibility, suitability, compliance, and privacy questions require Terms, Privacy, Risks, or owner-reviewed materials. Documentation alone is not legal, financial, tax, or investment advice. - URLs shown in each section are canonical docs routes for this exported content. # Protocol concepts Protocol architecture, audiences, core mechanics, economics, governance, and risk references. ## Unlocking credit for RWAs Source: https://docs.gearbox.finance/core/unlocking-credit-for-rwas File: content/core/unlocking-credit-for-rwas.mdx Purpose-built for RWAs, Gearbox’s lending infrastructure combines capital efficiency, compliance-aware execution, and institutional-grade leverage in a way no existing onchain lending protocol can. Most lending protocols treat RWAs like any other ERC-20 token. While this enables basic compatibility, it prevents enforcement of issuer-defined rules such as redemption, settlement, withdrawals, and deposits, leaving RWA credit structurally limited. Gearbox is built differently. Credit is extended at the RWA protocol level, not just the token level. Credit Accounts interact directly with issuer contracts, allowing purpose-specific rules to be enforced by design. This enables compliant, programmable leverage optimized for RWAs, without compromising issuer controls or asset mechanics. ## No DEX dependency Gearbox is built to work with RWA-specific on-chain logic. Credit Accounts interact directly with issuer contracts, ensuring leverage respects the asset’s native lifecycle by design. This direct integration allows credit users to mint and redeem RWAs with borrowed capital, bypassing secondary markets like DEXes altogether. **As a result:** * **Issuers save millions of dollars** for bootstrapping and subsidizing DEX liquidity * **Users save months of yield** by always redeeming at face value instead of selling at discount ## Launch faster, focus on distribution Traditional looping methods don’t suit RWA leverage. They fragment UX with multi-step, multi-protocol transactions and become highly capital-inefficient when redemption periods are long. Most lending protocols require 5+ transactions across the lending platform and the asset issuer to take a leverage on RWA token, effectively limiting access to advanced on-chain users only. ### Gearbox's Benefits * **Zero DEX Liquidity Required:** With Gearbox, leverage can go live on day one. It eliminates the need for DEX liquidity seeding, working at any size. * **Improved distribution:** User can enter leveraged position in one transaction. * **Capital savings worth months of yield:** * Save time up to **8 periods** of native redemption. * Capital requirements are reduced by **10x**. * Save fees equal to a **month of farming yield**. * **Risk Control:** Automated deleverage reduces liquidation risk, capital stays in user-owned segregated wallet minimizing indirect exposure. ## Compliant interaction by Design It is almost impossible to enforce transfer-agent/compliance obligations on-chain in traditional pools-based lendings. Gearbox is designed for compliant access. * **Position Isolation:** Each user's position is fully isolated, preventing the mixing of assets or risk between accounts. * **Access Control:** Supports KYC- and rules-based access control, including per-account whitelists, jurisdiction filters, and configurable limits. * **On-Chain Enforcement:** Built-in position freezing and granular operation controls (what can be traded, where, and when) allows curator to enforce regulatory obligations on-chain. ***If you're building onchain RWA product, reach out to Gearbox to power it with Distribution-focused UX and capital-efficient execution.*** ## Learn in details | | | | Cover image | |---|---|---|---| | Improve UX and Capital EfficiencyUserbase growth without depending on liquidity | | [Usecase: Direct Redemptions](https://docs.gearbox.finance/core/usecase-direct-redemptions) | [gearboxdocsmain.png](https://docs.gearbox.finance/assets/docs/core/gearbox-permissionless-for-curators/01-gearbox-docs-main-page.png) | ## Guide for Asset Issuers Source: https://docs.gearbox.finance/core/guide-for-asset-issuers File: content/core/guide-for-asset-issuers.mdx Most lending protocols treat complex DeFi asset like any other ERC-20 token. While this enables basic compatibility, it prevents enforcement of issuer-defined rules such as redemption, settlement, withdrawals, and deposits. Gearbox is built differently. Credit is extended at the asset's protocol level, not just the token level. Credit Accounts interact directly with issuer contracts, allowing purpose-specific rules to be enforced by design. ## No DEX dependency Gearbox is built to work with asset-specific on-chain logic. Credit Accounts interact directly with issuer contracts, ensuring leverage respects the asset’s native lifecycle by design. This direct integration allows credit users to mint and redeem assets with borrowed capital, bypassing secondary markets like DEXes altogether. This is especially important for assets with longer redemption periods, as DEX liquidity is costly and ineffective there. **As a result:** * **Issuers save millions of dollars** for bootstrapping and subsidizing DEX liquidity * **Users save months of yield** by always redeeming at face value instead of selling at discount ## Launch faster, focus on distribution Traditional looping methods don’t suit leverage for novel assets. They fragment UX with multi-step, multi-protocol transactions and become highly capital-inefficient when redemption periods are long. Most lending protocols require 5+ transactions across the lending platform and the asset issuer to take a leverage on asset, effectively limiting access to advanced on-chain users only. ### Gearbox's Benefits * **Zero DEX Liquidity Required:** With Gearbox, leverage can go live on day one. It eliminates the need for DEX liquidity seeding, working at any size. * **Improved distribution:** User can enter leveraged position in one transaction. * **Capital savings worth months of yield:** * Save time up to **8 periods** of native redemption. * Capital requirements are reduced by **10x**. * Save fees equal to a **month of farming yield**. * **Risk Control:** Automated deleverage reduces liquidation risk, capital stays in user-owned segregated wallet minimizing indirect exposure. ## Widest collateral support & direct DeFi integration Credit Accounts accept nearly any on-chain position as collateral: LP tokens, staked assets, vault shares, and non-tokenized positions such as redemption receipts. This expands TVL, deepens liquidity, and unlocks leveraged versions of your asset’s native strategies. ***If you want to grow your DeFi product, whether it’s an LRT, vault, or any other productive collateral, reach out to Gearbox to power it with Distribution-focused UX and capital-efficient execution.*** ## Case studies | | | Cover image | |---|---|---| | P2P vault growthHow P2P's mellow LRT has grown from 25k to 45k restaked wstETH | [case-study-mellow-x-p2p-lrt-growth-powered-by-gearbox](https://docs.gearbox.finance/core/case-study-mellow-x-p2p-lrt-growth-powered-by-gearbox) | [gearboxdocsmain.png](https://docs.gearbox.finance/assets/docs/core/gearbox-permissionless-for-curators/01-gearbox-docs-main-page.png) | ## Learn in details | | Cover image | | |---|---|---| | Direct redemptionsUsers save months of yield; Asset issuers - millions on DEX incentives | [gearboxdocscurate.png](https://docs.gearbox.finance/assets/docs/core/gearbox-permissionless-for-curators/03-gearbox-docs-curate-page.png) | [Usecase: Direct Redemptions](https://docs.gearbox.finance/core/usecase-direct-redemptions) | | User-first executionIntegrate leverage into product offering as if it were there by design | [gearboxdocsborrow.png](https://docs.gearbox.finance/assets/docs/core/gearbox-permissionless-for-curators/04-gearbox-docs-borrow-page.png) | [Adapters & Integrations](https://docs.gearbox.finance/core/adapters-integrations) | ## Gearbox Permissionless for Curators Source: https://docs.gearbox.finance/core/gearbox-permissionless-for-curators File: content/core/gearbox-permissionless-for-curators.mdx Gearbox Permissionless provides the operational rails for institutions, asset managers, and fintechs to deploy onchain credit markets. **Curator**, acts as the operator of a standalone lending vertical. This role is designed for entities seeking to retain full ownership of their market's risk parameters and economic model, while leveraging Gearbox’s battle-tested settlement engine to handle execution, solvency, and compliance. This page outlines the operational model and strategic advantages of the Gearbox curation stack. ## Market Curation, Not Fund Management In many onchain lending models, curation requires active capital reallocation, manually moving funds between vaults to chase yield. This creates significant operational burden and can inadvertently classify operators as financial intermediaries or asset managers. **The Gearbox Approach:**\ Curators manage **Parameters**, not **Funds**. * **Non-Custodial:** Curator defines the rules (LTVs, Interest Rate Models), but never possesses or controls user funds. * **Automated Execution:** The protocol automatically allows credit usage within allowed limits and enforces solvency based on pre-defined logic. * **Compliance Benefit:** This passive model allows you to operate a lending business without engaging in active fund management activities. ## Structured Credit Products Standard lending markets are commoditized, offering simple borrowing against collateral. Gearbox enables Curators to structure complex **Credit Products**. * **Strategy Integration:** Deploy markets that offer native access to specific yield strategies (e.g., Leveraged Staking, Basis Trading, or RWA accumulation). * **Capital Efficiency:** By integrating execution directly into the credit account, Curators can offer higher leverage ratios with tighter risk controls than standard over-collateralized lending. ## Institutional-Grade Risk Framework For asset issuers and fund managers, security is the primary constraint. Gearbox provides a multi-layered safety stack designed for high-value deployments. * **Dual-Oracle Architecture:** Markets utilize a primary and secondary oracle source to prevent price manipulation and ensure accurate mark-to-market valuations. * **Automated Insolvency Resolution:** The "Loss Policy" mechanism provides pre-defined logic for handling bad debt events, protecting Liquidity Providers from black swan scenarios. * **Granular Access Control:** Curators can deploy permissioned instances, utilizing allowlists for borrowers or lenders to meet KYC/AML requirements. ***If you’re expanding your product offering, reach out to Gearbox to power your lending vertical with superior UX and a safety-first design.*** ![Figure](https://docs.gearbox.finance/assets/docs/core/gearbox-permissionless-for-curators/01-gearbox-docs-main-page.png) ### Get started Create a market and make first steps towards launching a lending product. **Become a Market Curator** ## Learn in details | | Cover image | | |---|---|---| | Collateral-specific ratesNon-custodial by design. Capital-efficient by default | [gearboxdocsmain.png](https://docs.gearbox.finance/assets/docs/core/gearbox-permissionless-for-curators/01-gearbox-docs-main-page.png) | [Collateral Limits & Specific Rates](https://docs.gearbox.finance/core/collateral-limits-specific-rates) | | Dual-oracle system & bad debt preventionA safety-first mechanisms for LP protection | [gearboxdocscurate.png](https://docs.gearbox.finance/assets/docs/core/gearbox-permissionless-for-curators/03-gearbox-docs-curate-page.png) | [Smart Oracles](https://docs.gearbox.finance/core/smart-oracles) | | Multichain ScalingGrow across ecosystems with ready-to-use infrastructure | [gearboxdocsborrow.png](https://docs.gearbox.finance/assets/docs/core/gearbox-permissionless-for-curators/04-gearbox-docs-borrow-page.png) | [Omni-EVM Architecture](https://docs.gearbox.finance/core/omni-evm-architecture) | | Native integrations for superior UXOffer users best-in-class capital-efficiency | [gearboxdocuses.png](https://docs.gearbox.finance/assets/docs/core/gearbox-permissionless-for-curators/05-gearbox-docs-use-cases-page.png) | [Adapters & Integrations](https://docs.gearbox.finance/core/adapters-integrations) | ## Wallet-native Credit powered by Credit Accounts Abstraction Source: https://docs.gearbox.finance/core/wallet-native-credit-powered-by-credit-accounts-abstraction File: content/core/wallet-native-credit-powered-by-credit-accounts-abstraction.mdx > One Click, Infinite Utility: No more bridging to external dApps. No more locking assets in inaccessible vaults. Your wallet is the protocol. ## Transforming Wallets into Crypto Neobanks Imagine a bank account where you can only store money, not borrow or use credit. That’s what most crypto wallets look like today. Gearbox changes the landscape of decentralized finance by embedding a credit layer directly into wallets, turning them into “Crypto Neobanks”. Users gain access to credit lines against their existing collateral. Gearbox serves as the invisible “credit rails,” while the Wallet Provider acts as the user-facing financial app. ### Native Credit Integration via Account Abstraction The user doesn't see complex smart contract interactions. They simply toggle "Credit Mode" or switch to their "Credit Account" tab, just like switching between a Credit and Savings account ### Seamless DeFi compatibility Unlike traditional lending protocols that lock your assets away, the system recognizes tokens in the wallet as collateral automatically. Users don't just "borrow" funds; they use them. The credit line works across major DeFi protocols (Uniswap, Curve, Pendle). ### Two Modes, One Wallet **For the Spender (The "Crypto Credit Card"):** Integrate with Gnosis Pay/Holyheld or other crypto cards. Users can pay for groceries and daily needs using a stablecoin credit line. **For the Investor (The "DeFi Powerhouse"):** Execute complex strategies (e.g., "Invest into fixed-yield PT token with 5x leverage") directly from the wallet UI. No need for external operational overhead. ## Proof of concept **(Coinbase Wallet Example)** The integration requires no clunky approvals for every action. The wallet recognizes the Credit Account as a native environment, enabling a smooth, "Web2-like" financial experience. []() ***If you’re building wallet-native credit, reach out to Gearbox to power it with seamless execution and a superior UX.*** ## Learn in details | | Cover image | |---|---| | How it works | [gearboxdocsmain.png](https://docs.gearbox.finance/assets/docs/core/gearbox-permissionless-for-curators/01-gearbox-docs-main-page.png) | | | | ## About Gearbox Source: https://docs.gearbox.finance/core/about-gearbox File: content/core/about-gearbox.mdx Gearbox is onchain credit infrastructure for building lending and leverage products. It connects passive capital in pools with borrowers who use Credit Accounts to take positions across approved partner protocols. The core primitive is simple: a **Credit Account is a wallet with credit**. It can hold collateral, borrow from a pool, and execute approved actions, while every action must keep the account solvent under protocol rules. Gearbox started in 2021 as a protocol for DeFi investing with leverage. It then evolved through V2, V3, and V3.1 from a strategy-focused leverage product into infrastructure for purpose-built credit markets, RWA-backed debt positions, and wallet-native lending products. The current architecture combines two goals: - **Wallet-like UX:** users or products operate through an account that can hold assets, debt, and execution routes in one place. - **Lending-protocol efficiency:** capital is supplied by pools, priced through protocol parameters, and protected by solvency checks, liquidation rules, and debt ceilings. ## Two sides of the system ### Pool side: passive capital A pool is the savings product in Gearbox. Lenders deposit an asset into a pool and earn yield from interest paid by borrowers using that liquidity. The pool does not make strategy decisions for each borrower. It allows borrowing by Credit Accounts under explicit debt ceilings. This keeps passive capital aggregated while limiting how much exposure any one market or strategy can take from the pool. A pool is not a bank deposit or guaranteed yield product. It is an onchain lending position with protocol, market, liquidity, and liquidation risk. ### Credit Account side: wallet with credit A Credit Account is a user-controlled smart-contract account that combines collateral, debt, and approved execution routes. Borrowers do not receive unrestricted funds. They operate inside a Credit Account. The account can interact with approved partner protocols, but each action is checked against collateral values, Liquidation Thresholds, allowed assets, and market-specific rules. This lets a product expose a wallet-like experience while the protocol enforces credit boundaries in the background. ## How capital moves 1. Lenders deposit assets into a pool. 2. The pool allows borrowing by Credit Accounts within configured debt ceilings. 3. Borrowers open or use Credit Accounts. 4. Credit Accounts deploy borrowed liquidity into approved strategies or products. 5. Borrowers pay interest back to the pool. 6. Solvency checks and liquidation rules protect the pool when a Credit Account becomes unsafe. ## What this enables For lenders, Gearbox turns a pool into a passive lending product. The lender does not need to choose every borrower or strategy manually, while risk remains bounded by market configuration. For borrowers, Gearbox turns leverage into an account-level credit line. The borrower can use capital inside a Credit Account without repeatedly moving assets through separate lending, trading, and strategy interfaces. For curators and builders, Gearbox provides the infrastructure to create specialized credit products. A market can define supported assets, debt ceilings, rates, oracle rules, and liquidation parameters for a specific use case. ## Where to go next - [One Pool, Many Markets](https://docs.gearbox.finance/core/one-pool-many-markets): how one passive liquidity source can fund multiple isolated markets. - [Credit Accounts (The Primitive)](https://docs.gearbox.finance/core/credit-accounts-the-primitive): the account model that makes wallet-native credit possible. - [Pool (The Liquidity Vault)](https://docs.gearbox.finance/core/pool-the-liquidity-vault): how passive lending capital is deposited, represented, and used. - [Gearbox Permissionless for Curators](https://docs.gearbox.finance/core/gearbox-permissionless-for-curators): how curators create and operate markets. ## One Pool, Many Markets Source: https://docs.gearbox.finance/core/one-pool-many-markets File: content/core/one-pool-many-markets.mdx Gearbox Protocol separates the source of liquidity from the utilization of liquidity. This architecture allows a single passive liquidity source to fund diverse, isolated lending strategies simultaneously. ![Figure](https://docs.gearbox.finance/assets/docs/core/one-pool-many-markets/01-one-pool-many-markets.png) ## The Wholesale Bank Model To understand the flow of capital, view the architecture through the analogy of a banking system: ### 1. The Pool (The Wholesale Bank) The Liquidity Pool acts as a **Wholesale Bank**. It is a massive, passive reservoir of capital (e.g., USDC, WETH, or DAI). * **Role:** It accepts deposits from lenders and holds the funds securely. * **Mandate:** It does not lend directly to end-users. Instead, it lends capital to "Retail Branches" (Credit Suites) based on strict credit limits. ### 2. Credit Suites (The Retail Branches) Credit Suites (technically "Credit Managers") act as **Retail Branches**. Each branch is a specialized lending product with a specific mandate. * **Role:** They borrow liquidity from the Wholesale Bank (Pool) to fund Credit Accounts for users. * **Mandate:** Each suite defines a specific strategy, such as "Low-Risk Stablecoin Farming" or "High-Leverage ETH Staking." ![Figure](https://docs.gearbox.finance/assets/docs/core/one-pool-many-markets/02-2-credit-suites-the-retail-branches.png) This separation allows the protocol to offer low-risk and high-risk products side-by-side without fragmenting liquidity. ## Risk Isolation (Debt Ceilings) In a monolithic lending protocol, bad debt in one asset can drain the entire pool. Gearbox prevents this via **Risk Isolation**. The Pool assigns a **Debt Ceiling** to each Credit Suite. This is the maximum amount of capital that specific branch can borrow from the bank. * **Scenario:** A Pool holds $100M USDC. * **Allocation:** * $80M is allocated to a "Blue Chip Strategy" (Low Risk). * $10M is allocated to an "Emerging Asset Strategy" (High Risk). * **Isolation:** If the "Emerging Asset Strategy" suffers a catastrophic failure, the maximum loss to the Pool is capped at $10M. The remaining $90M is mathematically isolated from that specific risk vector. This ensures that lenders are protected from the tail risks of specific aggressive strategies, while still benefiting from the higher utilization they generate. ## The Diesel Token (Unified Yield) Lenders interact only with the Pool. When they deposit assets, they receive **Diesel Tokens** (e.g., dUSDC, dWETH). * **Unified Exposure:** The Diesel Token represents a pro-rata share of the entire Wholesale Bank's assets. * **Aggregated Yield:** The yield is generated by the interest paid by *all* connected Credit Suites. Whether the capital is used for staking, farming, or trading, the interest flows back to the Pool and appreciates the value of the Diesel Token. This abstracts the complexity of multiple markets away from the lender. The lender provides liquidity once and earns a blended yield from a diversified basket of on-chain credit strategies. ## Learn More * **Technical Implementation:** How the passive vault handles deposits and withdrawals. * [pool](https://docs.gearbox.finance/core/pool-the-liquidity-vault) * **Market Configuration:** How specific rules and strategies are defined for each branch. * [credit-suite](https://docs.gearbox.finance/developers/credit-suite) ## Credit Accounts (The Primitive) Source: https://docs.gearbox.finance/core/credit-accounts-the-primitive File: content/core/credit-accounts-the-primitive.mdx The Credit Account is the fundamental primitive of the Gearbox Protocol. It functions as a user-owned, isolated smart contract wallet that holds both collateral and borrowed funds, enabling leveraged execution across DeFi protocols. ## Core Concept: Isolated Smart Contract Wallet Unlike traditional lending protocols where user collateral is siloed in a global vault, Gearbox deploys a unique smart contract for each borrower. ![Figure](https://docs.gearbox.finance/assets/docs/shared/legacy-lending.png) The Credit Account serves as a container for the user's entire position. * **Segregated State:** Assets within the Credit Account are legally and technically distinct from the protocol's liquidity pools. * **User Ownership:** The user retains control over the account's operations, subject only to the solvency checks enforced by the Credit Manager. * **Portability:** Because the Credit Account is a standard smart contract, it can interact with external protocols as a distinct entity, preserving the identity of the position. ## Atomic Solvency Check The Credit Account operates on a "Check-on-Exit" architecture. The protocol does not restrict specific actions within a transaction bundle, provided the account remains solvent at the conclusion of the execution trace. Upon the completion of any interaction (e.g., a swap or deposit), the protocol calculates the account's **Health Factor**. * **If Health Factor > 1:** The transaction is finalized and recorded on-chain. * **If Health Factor < 1:** The entire transaction reverts, ensuring no bad debt can be created atomically. This mechanism allows users to perform complex, multi-step operations in a single transaction without requiring the protocol to understand the intermediate states, as long as the final state satisfies the risk parameters. ![Figure](https://docs.gearbox.finance/assets/docs/shared/credit-account-lending.png) ## Composability via Adapters The Credit Account interacts with the external DeFi ecosystem through **Adapters**. These are lightweight contract interfaces that translate generic user intents into protocol-specific function calls. From the perspective of an external protocol, the Credit Account appears as a standard user wallet. This enables: 1. **Native Execution:** Users interact directly with external contracts rather than through a protocol-specific abstraction layer. 2. **Programmable Credit:** Developers can compose credit logic into arbitrary workflows, treating the Credit Account as a programmable leverage module. *** ## Learn More * **Risk Enforcement:** the logic for calculating the Health Factor and enforcing solvency is managed by the Credit Manager and Credit Facade. * [credit-suite](https://docs.gearbox.finance/developers/credit-suite) * **External Interactions:** The mechanism for connecting Credit Accounts to external DeFi protocols is defined by the Adapter system. * [adapters-integrations](https://docs.gearbox.finance/core/adapters-integrations) * **Liquidity Source:** The capital borrowed by the Credit Account is sourced from the passive Liquidity Pool. * [pool](https://docs.gearbox.finance/core/pool-the-liquidity-vault) ## Omni-EVM Architecture Source: https://docs.gearbox.finance/core/omni-evm-architecture File: content/core/omni-evm-architecture.mdx Gearbox Protocol is designed as a **Deployable Primitive** rather than a monolithic cross-chain application. It does not rely on bridges for message passing or state synchronization between chains. Instead, every deployment on a new chain is a standalone, self-contained **Instance**. This architecture ensures that risk is isolated to the specific chain and that the protocol can scale permissionlessly to any EVM-compatible network without waiting for centralized bridge infrastructure. ## Modular Instances An **Instance** is a complete, functional replica of the Gearbox Protocol deployed on a specific blockchain network. * **Independence:** Each Instance operates autonomously. A failure or pause on one chain does not propagate to others. * **No Bridge Dependency:** Core protocol functions (borrowing, lending, liquidations) do not require cross-chain messaging. * **Local Configuration:** Parameters are tuned specifically for the local ecosystem (e.g., block times, gas costs, and available liquidity) rather than inheriting global defaults that may not fit. This modularity allows the protocol to exist natively on high-speed L2s or sidechains while maintaining the security standards established on Mainnet. ## Bytecode Repository (Verifiable Deployment) To ensure security across many independent instances, Gearbox utilizes a **Bytecode Repository**. This acts as an onchain "Source of Truth" for protocol logic. 1. **Global Verification:** The Gearbox DAO votes to approve specific contract versions (e.g., `CreditFacade V3.1`) after audits are completed. 2. **Onchain Storage:** The compiled bytecode of these approved contracts is stored in the Bytecode Repository on the canonical chain. 3. **Trustless Deployment:** When a new Instance is deployed or updated, the factory contracts verify that the code being deployed matches the authorized bytecode in the repository. This mechanism guarantees that every Instance, regardless of who deployed it, runs the exact, audited code approved by the DAO. ## Governance Architecture Because Instances are independent, governance is split into **Global** (Code & IP) and **Local** (Configuration & Risk) layers. This separation of concerns allows for efficient scaling without creating a bottleneck at the DAO level. | Entity | Scope | Responsibility | | ------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------- | | **Protocol DAO** | Global (All Chains) | Manages the codebase, approves new versions, and governs the Bytecode Repository. | | **Instance Owner** | Local (One Chain) | A technical multisig responsible for chain-specific infrastructure, such as whitelisting local price feeds. | | **Market Curators** | Local (Specific Markets) | Independent operators who deploy lending markets and manage economic risk parameters (LTVs, Rates). | ## Learn More * **Protocol ownership:** How are the token holders' financial interests and the delivery of the core codebase managed? * [protocol-dao](https://docs.gearbox.finance/core/protocol-dao) * **Chain-specific oversight:** Safe operation within a chain. * [instance-owner](https://docs.gearbox.finance/core/instance-owner) * **Markets growth:** Who manages business building and specific risk parameters? * [market-curators](https://docs.gearbox.finance/core/market-curators) ## For Lenders & LPs Source: https://docs.gearbox.finance/core/for-lenders-lps File: content/core/for-lenders-lps.mdx ## Phase 1: Structural Risk Assessment (Mental Model) **User Intent:** Evaluate the fundamental architecture to determine if the risk segregation meets investment mandates. | Key Question | System Answer | Sitemap Component | | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | **"How is liability vs. asset risk structured?"** | **Segregated Risk Architecture.** The protocol decouples passive liquidity (Pool) from active risk strategies (Credit Managers). A failure in one strategy is contained by its specific debt ceiling, protecting the broader pool. | [one-pool-many-markets](https://docs.gearbox.finance/core/one-pool-many-markets) | | **"Is the deployment canonical?"** | **Omni-EVM Architecture.** Gearbox utilizes a modular deployment model. Each chain operates as an independent, verified instance rather than a bridged dependency. | [omni-evm-architecture](https://docs.gearbox.finance/core/omni-evm-architecture) | ## Phase 2: Yield Mechanics & Liquidity Risk **User Intent:** Analyze the mechanism of yield accrual and the constraints on capital withdrawal. | Key Question | System Answer | Sitemap Component | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | **"How does capital accrue interest?"** | **The Liquidity Vault.** Yield accrues via the Diesel Token (ERC-4626), a non-rebasing interest-bearing token. The exchange rate appreciates as interest is paid by borrowers. | [pool](https://docs.gearbox.finance/core/pool-the-liquidity-vault) | | **"What drives APY volatility?"** | **Interest Rate Model.** The base rate is dynamic, driven by the utilization curve. The "Kink" ($U\_{optimal}$) defines the target efficiency range before rates scale exponentially. | [interest-rate-model](https://docs.gearbox.finance/core/interest-rate-model) | | **"What is the liquidity risk?"** | **Utilization Caps.** High utilization can temporarily block withdrawals. The Interest Rate Model is designed to force borrower repayment during these periods to restore exit liquidity. | [interest-rate-model](https://docs.gearbox.finance/core/interest-rate-model) | ## Phase 3: Counterparty Risk & Solvency Enforcement **User Intent:** Assess the creditworthiness of the borrowers and the automated enforcement of debt obligations. | Key Question | System Answer | Sitemap Component | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"What prevents fund misappropriation?"** | **Execution Guardrails.** Borrowers cannot access funds directly. They operate through **Credit Accounts** (smart contract wrappers) restricted to whitelisted interactions via Adapters. | [credit-suite](https://docs.gearbox.finance/core/credit-suite-the-strategy-module) \ [adapters-integrations](https://docs.gearbox.finance/core/adapters-integrations) | | **"How is solvency enforced?"** | **Liquidation Dynamics.** Solvency is enforced mathematically via the Health Factor ($H\_f$). If $H\_f < 1$, the protocol incentivizes third-party liquidators to seize collateral and repay debt. | [liquidation-dynamics](https://docs.gearbox.finance/core/liquidation-dynamics) | | **"How are assets valued?"** | **Price Oracle.** Asset valuation relies on normalized price feeds. Understanding the oracle source (Spot vs. TWAP) is critical for modeling liquidation triggers. | [price-oracle](https://docs.gearbox.finance/core/price-oracle) | ## Phase 4: Stress Testing & Failure Modes **User Intent:** Evaluate system resilience under adverse market conditions (Oracle attacks, Liquidity crunches). | Key Question | System Answer | Sitemap Component | | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | **"Is the system resilient to oracle manipulation?"** | **Smart Oracles.** The protocol employs a Dual-Feed architecture (Main vs. Reserve). Significant deviation between feeds blocks sensitive operations to prevent arbitrage. | [smart-oracles](https://docs.gearbox.finance/core/smart-oracles) | | **"How is concentration risk managed?"** | **Quota Keeper.** The protocol enforces **Asset-Side Limits**. Even if the pool has excess liquidity, exposure to specific volatile assets is capped globally. | [quota-controls](https://docs.gearbox.finance/core/collateral-limits-specific-rates) | | **"What happens if bad debt occurs?"** | **Insolvency Resolution.** The **Loss Policy** defines fallback logic (e.g., switching to fundamental pricing) to prevent selling collateral at distressed prices during flash crashes. | [smart-oracles](https://docs.gearbox.finance/core/smart-oracles) | ## Phase 5: Governance & Parameter Security **User Intent:** Verify that administrative privileges cannot be exploited to expropriate funds. | Key Question | System Answer | Sitemap Component | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | **"Who controls risk parameters?"** | **Market Curators.** Specific entities manage the risk parameters (LTVs, Limits) for their respective markets. | [market-curators](https://docs.gearbox.finance/core/market-curators) | | **"Are there protections against malicious updates?"** | **Timelock Constraints.** Critical parameter changes are subject to a mandatory 24-hour timelock, allowing LPs to withdraw capital before changes take effect. | [risk-configuration-dictionary](https://docs.gearbox.finance/core/risk-configuration-dictionary) | | **"Who controls the technical infrastructure?"** | **Instance Owner.** A chain-specific multisig acts as the technical gatekeeper for the Price Feed Store, ensuring oracle integrity independent of Market Curators. | [instance-owner](https://docs.gearbox.finance/core/instance-owner) | ## For Borrowers & Farmers Source: https://docs.gearbox.finance/core/for-borrowers-farmers File: content/core/for-borrowers-farmers.mdx ## Phase 1: Feasibility & Capacity Analysis **User Intent:** Determine if the protocol can support the target strategy size and complexity. | Key Question | System Answer | Sitemap Component | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"What constrains position size?"** | **Liquidity & Exposure Limits.** Capacity is bounded by two distinct factors: 1) Global liquidity availability in the Pool, and 2) Strategy-specific Debt Ceilings defined by the Curator. | [pool](https://docs.gearbox.finance/core/pool-the-liquidity-vault) \ [risk-configuration-dictionary](https://docs.gearbox.finance/core/risk-configuration-dictionary) | | **"What are the primary risk vectors?"** | **Risk Vector Identification.** Borrowers face three primary threats: 1) **Market Risk** (Collateral volatility), 2) **Rate Risk** (Utilization-driven cost spikes), and 3) **Liquidity Risk** (Inability to exit via external DEX liquidity). | [liquidation-dynamics](https://docs.gearbox.finance/core/liquidation-dynamics) | | **"Is the target collateral eligible?"** | **Collateral Allowlist.** Each Credit Manager enforces a strict allowlist of assets. Tokens not explicitly whitelisted cannot be held within the Credit Account. | [credit-suite](https://docs.gearbox.finance/core/credit-suite-the-strategy-module) | ## Phase 2: Cost of Carry Modeling **User Intent:** Model the dynamic cost of capital to project net yield and volatility exposure. | Key Question | System Answer | Sitemap Component | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **"What drives the base rate?"** | **Interest Rate Model.** Rates are dynamic and determined by **Pool Utilization**. Large withdrawals by LPs can cause immediate utilization spikes, increasing the cost of capital. | [interest-rate-model](https://docs.gearbox.finance/core/interest-rate-model) | | **"Are there asset-specific premiums?"** | **Quota Rates.** Illiquid or high-volatility collateral assets may carry an *additional* interest premium (Quota Rate) imposed by the Quota Keeper, independent of the base pool rate. | [quota-controls](https://docs.gearbox.finance/core/collateral-limits-specific-rates) | | **"What is the protocol take rate?"** | **Interest Fee.** The Curator and DAO capture a fixed percentage of the interest paid. This markup is additive to the base rate paid to LPs. | [risk-configuration-dictionary](https://docs.gearbox.finance/core/risk-configuration-dictionary) | ## Phase 3: Solvency & Liquidation Mechanics **User Intent:** Define the liquidation boundary and the economic consequences of insolvency. | Key Question | System Answer | Sitemap Component | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | | **"What triggers liquidation?"** | **Liquidation Triggers.** Insolvency can result from: 1) Collateral depreciation, 2) Debt asset appreciation, or 3) **Accrued Interest** (Rate spikes eroding the Health Factor). | [liquidation-dynamics](https://docs.gearbox.finance/core/liquidation-dynamics) | | **"What is the penalty structure?"** | **Liquidation Premium.** Upon liquidation, the borrower forfeits a fixed percentage (e.g., 5%) of the liquidated collateral to the third-party liquidator. | [liquidation-dynamics](https://docs.gearbox.finance/core/liquidation-dynamics) | | **"Are automated mitigations available?"** | **Partial Liquidation & Deleverage.** The protocol supports partial liquidations to restore solvency without full closure. Automated deleveraging tools can be utilized to maintain the Health Factor. | [liquidation-dynamics](https://docs.gearbox.finance/core/liquidation-dynamics) | ## Phase 4: Governance & Parameter Risk **User Intent:** Assess the risk of adverse parameter changes by the market operator. | Key Question | System Answer | Sitemap Component | | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **"Can parameters change mid-trade?"** | **Parameter Risk.** Yes. Curators can modify Liquidation Thresholds (LTVs). However, these changes are subject to a mandatory **Timelock**, providing a window for borrowers to adjust or exit. | [risk-configuration-dictionary](https://docs.gearbox.finance/core/risk-configuration-dictionary) | | **"What are the operational circuit breakers?"** | **Smart Oracles & Pauses.** 1) Significant deviation between Main and Reserve price feeds will block operations. 2) Admins retain the ability to pause Credit Managers in emergency scenarios. | [smart-oracles](https://docs.gearbox.finance/core/smart-oracles) | | **"Can access be revoked?"** | **Access Control.** Curators can forbid specific tokens or adapters, preventing borrowers from increasing exposure to those assets. | [market-curators](https://docs.gearbox.finance/core/market-curators) | ## Phase 5: Position Unwind & Liquidity Dependencies **User Intent:** Evaluate the reliability of exit mechanisms under stress. | Key Question | System Answer | Sitemap Component | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **"What are the execution dependencies?"** | **External Liquidity.** The "Atomic Close" relies on external DEX liquidity (e.g., Curve/Uniswap) to swap collateral for the debt asset. Thin liquidity or high slippage can cause repayment transactions to revert. | [adapters-integrations](https://docs.gearbox.finance/core/adapters-integrations) | | **"What is the contingency procedure?"** | **Manual Unwind.** If atomic execution fails, the borrower must manually withdraw collateral (subject to solvency checks), execute swaps externally, and repay the debt. | [credit-suite](https://docs.gearbox.finance/core/credit-suite-the-strategy-module) | ## For Market Curators Source: https://docs.gearbox.finance/core/for-market-curators File: content/core/for-market-curators.mdx The Market Curator views Gearbox as a **Risk Parameterization Engine**, not a fund management tool. Unlike other lending primitives where curators actively allocate liquidity (e.g., Morpho), Gearbox Curators define the *boundary conditions* (LTVs, Limits, Rates) within which users autonomously execute strategies. ## Phase 1: The Operational Model (Mental Model Alignment) **User Intent:** Understand the legal and operational distinction between "Managing Funds" and "Managing Parameters." | Key Question | System Answer | Sitemap Component | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **"Do I manage the liquidity?"** | **Non-Custodial Curation.** Unlike Morpho, Curators do not actively rebalance funds between vaults. Curators set the *rules* and users/borrowers autonomously utilize the liquidity. This distinction is critical for entities avoiding custodial classification. | [one-pool-many-markets](https://docs.gearbox.finance/core/one-pool-many-markets) | | **"What is the deliverable?"** | **The Lending Product.** The Curator's product is a set of smart contracts with specific risk parameters. The "Product" is the *access* to leverage and earning under these specific terms, not the yield itself. | [credit-suite](https://docs.gearbox.finance/core/credit-suite-the-strategy-module) | | **"Who bears the economic risk?"** | **Risk Liability.** The Curator bears the reputational and economic risk of their configuration. Gearbox Protocol provides the *mechanism* for liquidation, but the *guarantee* of solvency depends entirely on the Curator's parameter selection (LTV vs. Volatility). | [liquidation-dynamics](https://docs.gearbox.finance/core/liquidation-dynamics) | ## Phase 2: Infrastructure Dependencies (The "Full Stack" Reality) **User Intent:** Assess the reliance on Gearbox DAO for critical infrastructure vs. autonomous capabilities. | Key Question | System Answer | Sitemap Component | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **"Is it fully permissionless?"** | **Hybrid Governance.** While market creation is permissionless, critical infrastructure is gated. 1) **Chain Activation** requires DAO approval. 2) **Price Feed Whitelisting** is controlled by the Instance Owner multisig (though open to Curator participation). | [instance-owner](https://docs.gearbox.finance/core/instance-owner) | | **"Who runs the interface?"** | **UI & Tooling Dependency.** The official Gearbox App and Curation Interface are maintained by the DAO. While the protocol is onchain, practical operation relies on these offchain services unless the Curator builds their own frontend. | [protocol-dao](https://docs.gearbox.finance/core/protocol-dao) | | **"How are transactions generated?"** | **Operational Complexity.** Configuring a market involves complex transaction batches. Curators rely on the DAO-maintained **Curation Interface** to generate these payloads. Autonomous operation requires significant technical capability to replicate this tooling. | [risk-configuration-dictionary](https://docs.gearbox.finance/core/risk-configuration-dictionary) | ## Phase 3: Product Structuring & Incentives **User Intent:** Define the commercial structure and align incentives with the DAO. | Key Question | System Answer | Sitemap Component | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **"How do I monetize?"** | **Fee Sharing.** Curators capture a configurable percentage of interest and liquidation fees. This revenue stream is programmatic and shared with the Protocol DAO. | [market-curators](https://docs.gearbox.finance/core/market-curators) | | **"Can I get token incentives?"** | **DAO Alignment.** GEAR token incentives are discretionary and voted on by the DAO. There is no programmatic guarantee of incentives; Curators must align their product with the DAO's strategic goals to receive support. | [protocol-dao](https://docs.gearbox.finance/core/protocol-dao) | | **"Can the DAO interfere?"** | **Sovereignty vs. Support.** The DAO cannot alter a Curator's parameters onchain. However, the DAO *can* delist a market from the official UI or cut incentives if the Curator's risk management endangers the protocol's reputation. | [protocol-dao](https://docs.gearbox.finance/core/protocol-dao) | ## Phase 4: Risk Parameterization (The Core Job) **User Intent:** Calibrate the system to balance capital efficiency with solvency protection. | Key Question | System Answer | Sitemap Component | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | | **"How is leverage capped?"** | **Liquidation Thresholds.** Curators set the $LT$ for each asset. This is the primary lever for risk management. Setting this too high relative to asset volatility *will* result in bad debt, for which the protocol is not liable. | [liquidation-dynamics](https://docs.gearbox.finance/core/liquidation-dynamics) | | **"How is concentration risk managed?"** | **Quota Limits.** Curators must set global caps on specific collateral assets via the Quota Keeper. This prevents the pool from becoming over-exposed to illiquid tokens. | [quota-controls](https://docs.gearbox.finance/core/collateral-limits-specific-rates) | | **"How are liquidators incentivized?"** | **Liquidation Premium.** Curators configure the premium paid to liquidators. If this is set too low, liquidators will not execute, and the system *will* fail. The protocol does not guarantee liquidation execution. | [liquidation-dynamics](https://docs.gearbox.finance/core/liquidation-dynamics) | ## Phase 5: Operational Governance **User Intent:** Understand the ongoing management and emergency procedures. | Key Question | System Answer | Sitemap Component | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **"How are updates executed?"** | **Timelock Constraints.** All critical parameter changes are subject to a 24-hour timelock. Curators must plan updates in advance. | [risk-configuration-dictionary](https://docs.gearbox.finance/core/risk-configuration-dictionary) | | **"What are the emergency powers?"** | **Pause & Loss Policy.** In the event of an exploit or market failure, Curators (or their Emergency Admins) can pause borrowing or trigger the Loss Policy to prevent bad debt accumulation. | [smart-oracles](https://docs.gearbox.finance/core/smart-oracles) | ## For Ecosystems & Chains Source: https://docs.gearbox.finance/core/for-ecosystems-chains File: content/core/for-ecosystems-chains.mdx ## Phase 1: The Value Proposition (Composability Engine) **User Intent:** Understand how Gearbox enriches the existing DeFi ecosystem beyond simple lending. | Key Question | System Answer | Sitemap Component | | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **"How does this benefit local apps?"** | **Unified Execution Layer.** Gearbox is not a silo. Through **Adapters**, Credit Accounts inject leverage directly into local protocols (e.g., Uniswap, Curve, Pendle). This turns a passive lending market into an active volume generator for the chain's DEXs and yield farms. | [adapters-integrations](https://docs.gearbox.finance/core/adapters-integrations) | | **"Is it compatible with our assets?"** | **Versatile Collateral.** Gearbox supports complex assets like LP tokens, Vault shares, and PTs. This allows the chain to offer leverage on its unique "Productive Assets," not just plain vanilla tokens. | [credit-suite](https://docs.gearbox.finance/core/credit-suite-the-strategy-module) | ## Phase 2: The Operating Model (Roles & Responsibilities) **User Intent:** Clarify the division of labor between the Chain, the Gearbox DAO, and the Market Operators. | Key Question | System Answer | Sitemap Component | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **"Who runs the markets?"** | **Service Provider vs. Operator.** Gearbox DAO provides the *technology stack* (Service Provider). **Curators** (Operators) run the actual business (Risk/Parameters). The Chain can bring its own trusted curators, or Gearbox can help facilitate introductions to existing active curators. | [market-curators](https://docs.gearbox.finance/core/market-curators) | | **"Who guarantees success?"** | **Shared Responsibility.** Gearbox DAO ensures the code functions correctly and provides operational support. However, the economic success of a market is a function of the Curator's strategy and the Chain's underlying liquidity depth. | [protocol-dao](https://docs.gearbox.finance/core/protocol-dao) | | **"Is deployment gated?"** | **Permissionless Architecture.** No. Once the protocol is deployed on the chain, market creation is permissionless. Curators do not need Gearbox DAO approval to launch new markets or list new assets, ensuring rapid integration with the chain's roadmap. | [market-curators](https://docs.gearbox.finance/core/market-curators) | ## Phase 3: Ecosystem Prerequisites (Economic Viability) **User Intent:** Determine the maturity level required to support leveraged markets. | Key Question | System Answer | Sitemap Component | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **"What is required for liquidations?"** | **Liquidity Enables Capacity.** Gearbox relies on swapping collateral on local DEXs. Deeper DEX liquidity allows for higher borrowing limits. We work with chains to identify the most liquid assets suitable for initial markets. | [liquidation-dynamics](https://docs.gearbox.finance/core/liquidation-dynamics) | | **"How are liquidators onboarded?"** | **Collaborative Keeper Network.** Gearbox provides open-source liquidator bot infrastructure. We actively collaborate with the Chain to onboard local MEV searchers and keepers, ensuring a robust liquidation network is established pre-launch. | [liquidation-dynamics](https://docs.gearbox.finance/core/liquidation-dynamics) | | **"What assets work best?"** | **Productive Collateral.** Gearbox shines when there are yield-bearing assets (LSTs, LRTs, Yield Vaults). Leverage on zero-yield assets is less attractive to borrowers in high-rate environments. | [credit-suite](https://docs.gearbox.finance/core/credit-suite-the-strategy-module) | ## Phase 4: Technical Requirements (Deployment Feasibility) **User Intent:** Verify technical compatibility to ensure a smooth launch. | Key Question | System Answer | Sitemap Component | | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | **"What are the hard constraints?"** | **Block Gas Limit.** Gearbox contracts are sophisticated. To deploy the core infrastructure, the chain should ideally support a Block Gas Limit of **>30 Million**. We can assist in evaluating chain parameters for compatibility. | [omni-evm-architecture](https://docs.gearbox.finance/core/omni-evm-architecture) | | **"What infrastructure is needed?"** | **RPC Reliability.** Robust offchain operations (Interface, Liquidator Bots) require stable RPC providers. Gearbox contributors can assist in testing and verifying infrastructure readiness. | [omni-evm-architecture](https://docs.gearbox.finance/core/omni-evm-architecture) | | **"Are oracles ready?"** | **Oracle Infrastructure.** Reliable oracle providers (Chainlink, Redstone, Pyth, or API3) are required for collateral assets. We can help coordinate with oracle partners to ensure coverage. | [price-oracle](https://docs.gearbox.finance/core/price-oracle) | ## Phase 5: Growth & Incentives (Go-to-Market) **User Intent:** Plan the launch strategy and incentive allocation. | Key Question | System Answer | Sitemap Component | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **"How do we attract liquidity?"** | **Co-Marketing & Grants.** The Chain can offer incentives to Curators to encourage market creation. Gearbox DAO frequently partners with chains to co-market these launches to existing user base. | [market-curators](https://docs.gearbox.finance/core/market-curators) | ## For Asset Issuers & Protocols Source: https://docs.gearbox.finance/core/for-asset-issuers-protocols File: content/core/for-asset-issuers-protocols.mdx ## Phase 1: The Value Proposition (Distribution & Efficiency) **User Intent:** Understand how Gearbox drives growth for the underlying protocol. | Key Question | System Answer | Sitemap Component | | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **"How does this grow our TVL?"** | **Leverage as a Feature.** Gearbox acts as a multiplier on existing demand. By enabling users to mint/stake assets with leverage, issuers increase capital efficiency, attracting sticky, yield-focused capital that might otherwise go to competitors. | [credit-suite](https://docs.gearbox.finance/core/credit-suite-the-strategy-module) | | **"Does it require DEX liquidity?"** | **Zero-Slippage Execution.** Unlike standard lending markets, Gearbox does not strictly require deep DEX liquidity to enable leverage entry. Through **Direct Integration**, Credit Accounts can mint/redeem directly with protocol contracts, bypassing secondary market slippage entirely. | [adapters-integrations](https://docs.gearbox.finance/core/adapters-integrations) | | **"Can it handle complex flows?"** | **Purpose-Specific Execution.** Gearbox adapts to the asset's mechanics. Whether it's staking, locking, or vesting, the Credit Account executes the logic natively. This allows issuers to offer "Leveraged Staking" or "Leveraged RWA Vaults" as a seamless user experience. | [credit-suite](https://docs.gearbox.finance/core/credit-suite-the-strategy-module) | ## Phase 2: Solving the Liquidity Problem (RWAs & Vaults) **User Intent:** Address the specific friction points of illiquid or semi-liquid assets (RWAs, Private Credit). | Key Question | System Answer | Sitemap Component | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **"We have delayed settlement. Does it work?"** | **Async Redemption Support.** Yes. Standard lending protocols fail here, but Gearbox excels. Credit Accounts can initiate a redemption, hold the receipt token through the settlement period, and claim the underlying funds upon finalization—all while maintaining the credit position. | [adapters-integrations](https://docs.gearbox.finance/core/adapters-integrations) | | **"Do we need to pay for incentives?"** | **Capital Efficiency > Incentives.** By allowing users to mint assets at NAV (Net Asset Value) via leverage, issuers reduce the need to spend millions on incentives to deepen Curve/Uniswap pools just to support lending liquidations. | [liquidation-dynamics](https://docs.gearbox.finance/core/liquidation-dynamics) | | **"Can we enforce KYC/Whitelists?"** | **Compliance Compatibility.** Yes. Because the Credit Account is a smart contract wallet, it can be compatible with protocol allowlists or transfer restrictions, ensuring that leveraged users meet compliance requirements. | [credit-suite](https://docs.gearbox.finance/core/credit-suite-the-strategy-module) | ## Phase 3: Technical Integration (Adapters) **User Intent:** Assess the engineering effort required to connect. | Key Question | System Answer | Sitemap Component | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | **"How do we connect?"** | **The Adapter Model.** Integration requires building an **Adapter**—a lightweight wrapper contract that translates Gearbox's safety checks into the protocol's function calls (e.g., `deposit()`, `stake()`, `requestRedemption()`). | [adapters-integrations](https://docs.gearbox.finance/core/adapters-integrations) | | **"Who builds the adapter?"** | **Collaborative Development.** Gearbox DAO maintains a library of standard adapters (ERC-4626, Curve, Uniswap). For custom logic, teams can fork a template or collaborate with Gearbox contributors for guidance. | [adapters-integrations](https://docs.gearbox.finance/core/adapters-integrations) | ## Phase 4: Risk Underwriting (Getting Approved) **User Intent:** Understand how to satisfy the risk requirements of potential Curators. | Key Question | System Answer | Sitemap Component | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **"How is risk assessed?"** | **Curator Due Diligence.** There is no universal formula. Each Curator has a unique risk framework—some prioritize backing transparency, others prioritize secondary liquidity. Issuers should be prepared to provide data on volatility, redemption mechanics, and backing to facilitate this underwriting process. | [liquidation-dynamics](https://docs.gearbox.finance/core/liquidation-dynamics) | | **"How is the asset priced?"** | **Flexible Oracle Architecture.** Gearbox supports diverse pricing models (Spot, TWAP, Fundamental/NAV). The choice depends on what the Curator is comfortable with. Issuers should propose a pricing source that is robust against manipulation to increase the likelihood of listing. | [price-oracle](https://docs.gearbox.finance/core/price-oracle) | | **"How do we ensure solvency?"** | **Shared Assurance.** Curators need to know that liquidations will execute in bad market conditions. Issuers can significantly improve their listing chances by committing to run their own liquidator bots or providing a backstop for collateral liquidation. | [liquidation-dynamics](https://docs.gearbox.finance/core/liquidation-dynamics) | ## Phase 5: Go-to-Market (Decentralized Listing) **User Intent:** Navigate the listing process in a permissionless environment. | Key Question | System Answer | Sitemap Component | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **"Who approves the listing?"** | **Marketplace of Risk.** Gearbox is a neutral infrastructure; there is no central "Listing Committee." Issuers must pitch **Market Curators**—independent operators who manage the liquidity. Curators decide what to list based on their own risk models and incentive requirements. | [market-curators](https://docs.gearbox.finance/core/market-curators) | | **"What drives Curator decisions?"** | **Incentive Alignment.** Different Curators have different mandates. Some prioritize high-yield assets and may require incentives (bribes/points) to list new tokens. Others prioritize safety and require strict audits. Success requires finding the right Curator for the asset profile. | [market-curators](https://docs.gearbox.finance/core/market-curators) | | **"How fast can we launch?"** | **Permissionless Agility.** Once a Curator agrees to underwrite the asset, the listing is permissionless. There is no DAO governance vote required to add a new collateral type to an existing Credit Manager. | [market-curators](https://docs.gearbox.finance/core/market-curators) | ## Pool (The Liquidity Vault) Source: https://docs.gearbox.finance/core/pool-the-liquidity-vault File: content/core/pool-the-liquidity-vault.mdx The **Liquidity Pool** serves as the liability side of the Gearbox Protocol balance sheet. It is a passive, ERC-4626 compliant smart contract where lenders deposit assets (e.g., USDC, WETH) to earn yield. Unlike traditional lending protocols where a pool interacts directly with individual borrowers, the Gearbox Pool operates on a **Wholesale Banking Model**. It does not lend directly to users; instead, it allocates capital to **Credit Suites** (Credit Managers), which act as specialized lending branches with distinct risk configurations. ## Core Mechanics ### 1. Passive Liquidity & ERC-4626 The Pool is strictly passive. It holds the underlying asset and issues **Diesel Tokens** (dTokens) to depositors as a receipt of liquidity provision. * **Standard:** Fully compliant with [ERC-4626](https://www.google.com/url?sa=E\&q=https%3A%2F%2Feips.ethereum.org%2FEIPS%2Feip-4626) (Tokenized Vault Standard). * **Fungibility:** Diesel Tokens are fungible and transferable, allowing them to be used as collateral in other DeFi protocols. * **Liquidity:** Deposits and withdrawals are instant subject to available amount of unborrowed liquidity. ### 2. Diesel Tokens (Non-Rebasing Yield) Yield accrual in Gearbox is reflected through the **Exchange Rate**, not through balance updates. * **Non-Rebasing:** Unlike aTokens (Aave), the wallet balance of Diesel Tokens does not increase over time. * **Value Accrual:** As borrowers pay interest, the amount of underlying assets in the Pool grows while the supply of Diesel Tokens remains constant. Consequently, the exchange rate increases.\ Borrow rates are determined using Utilization-based Interest Rate Model and collateral-specific rates. $$ Exchange\ Rate = \frac{Total\ Assets\ (Principal + Interest)}{Total\ Supply\ of\ dTokens} $$ ### 3. The Branch Model (Wholesale Lending) The Pool delegates the complexity of risk management and borrower interaction to **Credit Suites**. * **The Pool (Wholesale Bank):** Aggregates liquidity from lenders. It has no knowledge of individual borrowers, collateral types, or liquidation logic. Its only function is to lend capital to approved Credit Suites up to a defined limit. * **Credit Suites (Retail Branches):** Borrow liquidity from the Pool to fund Credit Accounts. Each Credit Suite enforces specific risk parameters (LTV, allowed assets, liquidation rules). This separation of concerns ensures that the Pool remains lightweight and secure, while complexity is pushed to the periphery (the Suites). ## Risk Isolation & Allocation A single Pool can fund multiple Credit Suites simultaneously. The Market Curator manages the Pool's risk exposure by setting a **Debt Ceiling** for each connected Credit Suite. * **Allocation Limits:** The Curator defines the maximum capital available to each CreditSuite (e.g., 80% to a Low-Risk Product, 20% to a High-Risk Product). * **Firewalling:** If a specific Strategy (Credit Suite) suffers a failure or bad debt, the loss is contained within that Creit Suite's allocation. The Pool's exposure is limited to the capital lent to that specific branch, protecting the remaining liquidity. ## Automated Insurance mechanism Gearbox V3 implements an automated **First-Loss Capital** buffer to protect Passive Lenders from bad debt. This mechanism prioritizes protocol solvency over profit distribution by strictly retaining revenue within the until specific safety targets are met. ## Learn More * **Yield source:** How is the utilization-driven interest rate calculated? * [interest-rate-model](https://docs.gearbox.finance/core/interest-rate-model) * **Yield optimization & risk control:** How are collateral-specific rates and collateral exposure limits handled? * [quota-controls](https://docs.gearbox.finance/core/collateral-limits-specific-rates) * **Deposits utilization:** Where is the liquidity actually used or lent to? * [credit-suite](https://docs.gearbox.finance/developers/credit-suite) * **Insurance from Bad debt:** Learn how the underlying mechanism works in detail. * [insurance-and-solvency-reserves](https://docs.gearbox.finance/core/insurance-solvency-reserves) ## Credit Suite (The Strategy Module) Source: https://docs.gearbox.finance/core/credit-suite-the-strategy-module File: content/core/credit-suite-the-strategy-module.mdx The Credit Suite is the architectural assembly responsible for managing the asset side of the protocol's balance sheet. While the Liquidity Pool manages passive capital (liabilities), the Credit Suite defines the logic, risk parameters, and execution boundaries for active borrowers (assets). A single Liquidity Pool can be connected to multiple Credit Suites, each representing a distinct **Credit Manager** with unique risk configurations, allowed collateral assets, and borrowing limits. This isolation allows the protocol to compartmentalize risk strategies without fragmenting underlying liquidity. ## Architectural Components The Credit Suite consists of three primary smart contracts, each with distinct responsibilities regarding accounting, execution, and configuration. ### 1. Credit Manager (The Accountant) The Credit Manager is the central logic container and state manager for a specific lending strategy. It acts as the "Accountant" of the system. * **State Management:** It maintains the ledger of all Credit Accounts associated with the strategy, tracking debt amounts and collateral values. * **Adapter Registry:** It stores the list of approved Adapters (integrations) and enforces the "Allowlist" of tokens that can be held as collateral. * **Solvency Logic:** It contains the mathematical logic for calculating the Health Factor (HF). ### 2. Credit Facade (The Entry Point) The Credit Facade serves as the primary entry point for borrower interactions. It abstracts the complexity of the Credit Manager and enforces execution safety. * **Multicall Execution:** The Facade allows users to bundle multiple operations (e.g., `borrow`, `swap`, `deposit_into_vault`) into a single atomic transaction. * **Check-on-Exit Solvency:** The Facade implements the protocol's optimistic execution model. It permits any sequence of whitelisted operations during a transaction but enforces a strict solvency check at the end. * If HF > 1 at the end of the transaction, the state changes are committed. * If HF < 1, the entire transaction reverts. * **Permissions:** It handles user permissions, ensuring that only the owner of a Credit Account can initiate transactions affecting that account. **HF** calculation is based on **Total Weighted Value (TWV)** of collateral. This is not just the market value; it is the market value *discounted* by the Liquidation Threshold (LT). If Account holds $100 of ETH with an LT of 90%, the system values it at $90 for solvency purposes. * [**Deep Dive: Full Liquidation Math & Formulas**](https://docs.gearbox.finance/core/liquidation-dynamics) ### 3. Credit Configurator (The Management Layer) The Credit Configurator provides the administrative interface for Market Curators to manage the Credit Suite. It decouples governance logic from the core accounting logic. * **Parameter Updates:** Curators interact with the Configurator to adjust risk parameters (e.g., Liquidation Thresholds, Fees, Limits) rather than interacting with the Credit Manager directly. * **Validation & Safety:** The Configurator validates inputs to prevent invalid states (e.g., setting a Liquidation Threshold > 100%) before applying changes to the Credit Manager. * **Timelock Enforcement:** It enforces mandatory delays for critical parameter changes, ensuring users have time to react to risk adjustments before they become active. ## Interaction Flow 1. **Configuration:** The Curator sets risk parameters via the **Credit Configurator**. 2. **Execution:** The Borrower submits a multicall transaction to the **Credit Facade**. 3. **Accounting:** The Facade routes instructions to the **Credit Manager**, which updates the Credit Account's state and interacts with the **Pool** or **Adapters**. 4. **Verification:** The Facade requests a final solvency check from the Credit Manager before finalizing the transaction. ## Learn More * **Solvency enforcement:** How liquidations work? * [liquidation-dynamics](https://docs.gearbox.finance/core/liquidation-dynamics) * **Risk controls:** What is the complete list of parameters that define the strategy? * [risk-configuration-dictionary](https://docs.gearbox.finance/core/risk-configuration-dictionary) ## Adapters & Integrations Source: https://docs.gearbox.finance/core/adapters-integrations File: content/core/adapters-integrations.mdx A Credit Account is a secure "Container." By default, it cannot interact with the outside world because the protocol cannot guarantee the safety of external smart contracts. **Adapters** are the solution. They are specialized "Translation Contracts" that allow Credit Accounts to interact with specific DeFi protocols (like Uniswap, Curve, or Lido) while maintaining the strict solvency checks required by Gearbox. ## Modular Execution: Purpose-Optimized UX Gearbox’s modular architecture unifies credit and execution. * **The Core Layer:** Provides the capital and enforces solvency (Health Factor). * **The Adapter Layer:** Extends this base with purpose-specific execution rules. This allows Curators to design Financial Products tailored for specific use cases. One product might be optimized for **Prediction Markets** (interacting with order books), while another is optimized for **Yield Farming** (interacting with vaults). ![Figure](https://docs.gearbox.finance/assets/docs/core/adapters-integrations/01-modular-execution-purpose-optimized-ux.png) ## The Security Problem: Unrestricted Execution A Credit Account holds leveraged funds. If users could interact directly with any smart contract, they could exploit complex DeFi mechanics to bypass solvency checks. **How Adapters Fix This:**\ Adapters act as a **Sanitized Interface**. They restrict interactions to a specific, pre-defined set of functions that have been audited for safety. 1. **Function Whitelisting:** Users cannot call `any` function on Uniswap; they can only call the specific `swap` functions defined in the Adapter. 2. **Result Verification:** The Adapter ensures that the outcome of the trade (the tokens received) matches the protocol's expectations, preventing complex state manipulation attacks. By forcing all interactions through these "Safe Tunnels," Gearbox ensures that the Credit Account's state remains predictable at all times. ## The Router: Intelligent Execution While Adapters provide the *connection*, the **Router** provides the *path*. DeFi strategies are rarely simple. A user might want to "Zap" from USDC directly into a Convex Curve-stETH position. This requires multiple steps: 1. Swap USDC -> WETH (Uniswap) 2. Deposit WETH -> stETH (Lido) 3. Deposit stETH + WETH -> steCRV (Curve) 4. Stake steCRV -> Convex The Gearbox Router calculates the optimal path across all enabled Adapters and bundles these steps into a single **Multicall**. ![Figure](https://docs.gearbox.finance/assets/docs/core/adapters-integrations/02-the-router-intelligent-execution.png) ## Curator Responsibilities As a Curator, the choice of Adapters defines the **Utility** of the market. 1. **Enable Liquidity:** If a market accepts `wstETH` as collateral, the Curator should enable DEX Adapters (e.g., Uniswap or Curve) that support `wstETH` trading. Without it, users cannot swap into the Debt token. Limited allowed adapters will result in high slippage losses. 2. **Enable Yield:** To offer a "Farming Strategy," the Curator must enable the specific Adapter for that farm (e.g., the Convex Adapter or Midas vault adapter). 3. **Risk Management:** If a specific external protocol is hacked or becomes risky, the Curator can **Disable** that specific Adapter instantly via the Emergency Admin, protecting the pool from further exposure. ## Learn More * **Solvency checks:** How accounts are kept overcollateralized after each operation? * [credit-suite](https://docs.gearbox.finance/developers/credit-suite) * **Unique usecases:** How Credit Accounts and adapters unlock new credit interactions. * [direct-redemptions](https://docs.gearbox.finance/core/usecase-direct-redemptions) ## Interest Rate Model Source: https://docs.gearbox.finance/core/interest-rate-model File: content/core/interest-rate-model.mdx The Interest Rate Model (IRM) functions as the protocol's algorithmic central bank. Its primary objective is to balance **capital efficiency** (maximizing yield for lenders) with **liquidity availability** (ensuring lenders can withdraw assets). It achieves this by dynamically adjusting the Base Borrow Rate based on the **Utilization Rate** of the Liquidity Pool. ## The Utilization Curve The cost of borrowing is a function of demand. As the pool becomes more utilized (more funds borrowed), the interest rate rises to incentivize repayments and attract new deposits. Gearbox employs a **Two-Kink Piecewise Linear Model**. This design creates a specific "Optimal Zone" where rates remain stable, preventing volatility during normal market activity while aggressively penalizing over-utilization. ### Mathematical Structure The curve is defined by two utilization thresholds (Kinks), denoted as U\_1 and U\_2, creating three distinct slope zones: 1. **Growth Zone (0% to U\_1):** * **Behavior:** Rates increase slowly. * **Intent:** Incentivize early borrowing and ramp up utilization to efficient levels. 2. **Optimal Zone (U\_1 to U\_2):** * **Behavior:** Rates remain relatively stable or rise moderately. * **Intent:** Create a predictable cost of capital for borrowers while ensuring sufficient yield for lenders. This is the target operating range of the pool. 3. **Liquidity Crunch Zone (> U\_2):** * **Behavior:** Rates spike exponentially (High Slope). * **Intent:** Force immediate deleveraging. When utilization breaches U\_2, the cost of capital exceeds market returns, compelling borrowers to close positions and restoring liquidity for lender withdrawals. ### Formula The Borrow Rate R(U) is calculated as: $$ R(U)= \begin{cases} R\_{\text{base}} + \dfrac{U}{U\_1} R\_{\text{slope1}}, & U \le U\_1 \\\[6pt] R\_{\text{base}} + R\_{\text{slope1}} * \dfrac{U - U\_1}{U\_2 - U\_1} R\_{\text{slope2}}, & U\_1 < U \le U\_2 \\\[6pt] R\_{\text{base}} + R\_{\text{slope1}} + R\_{\text{slope2}} * \dfrac{U - U\_2}{1 - U\_2} R\_{\text{slope3}}, & U > U\_2 \end{cases} $$ Where: * U: Current Utilization Rate (Total Debt / Total Assets). * R\_base: The minimum starting rate (y-intercept). * R\_slope: The rate of change in each zone. ***Reference:*** * [Desmos IRM visualizer](https://www.desmos.com/calculator/d281eeb4a9) ## Liquidity Reservation A critical feature of the Gearbox IRM is the enforcement of **Exit Liquidity**. In standard lending protocols, 100% utilization means lenders cannot withdraw their funds until a borrower repays. Gearbox mitigates this risk through **Liquidity Reservation**. ### The Reservation Cap Curators can configure the market to strictly forbid new borrowing once utilization reaches U\_2. * **Mechanism:** If `isBorrowingMoreU2Forbidden` is enabled, any transaction attempting to increase debt beyond the U\_2 threshold will revert. * **Result:** The remaining liquidity (from U\_2 to 100%) is effectively reserved for lender withdrawals. Even in periods of peak demand, a buffer of liquid assets remains available in the pool. ## Total Cost of Capital The Interest Rate Model determines the **Base Rate** of the pool. The final cost to a borrower includes additional collateral-specific rate. ### Learn More * **Asset-specific risk premiums:** Borrowers holding specific collateral assets may incur an additional Quota Rate on top of the base rate. * [quota-controls](https://docs.gearbox.finance/core/collateral-limits-specific-rates) * **Protocol fees:** A portion of the interest paid is captured as revenue for the Protocol DAO and the Market Curator. * [dao-and-curators-business-model](https://docs.gearbox.finance/core/dao-curators-business-model) ## Collateral Limits & Specific rates Source: https://docs.gearbox.finance/core/collateral-limits-specific-rates File: content/core/collateral-limits-specific-rates.mdx The Quota Control system is the protocol's mechanism for managing concentration risk and pricing asset-specific exposure. While the Liquidity Pool provides a shared source of capital, the Quota system enforces strict limits on how that capital can be allocated toward specific collateral assets and applies additional risk premiums where necessary. ## Asset-Side Caps (Concentration Limits) To protect Liquidity Providers (LPs) from over-exposure to specific assets, the protocol enforces **Quota Limits**. These are hard caps on the total amount of debt that can be collateralized by a specific token across all Credit Managers attached to a pool. ### Mechanism Unlike a global debt ceiling which limits the total size of the pool or Credit Manager limits which define maximum exposure to particular strategies, Quota Limits operate on the **collateral side**. * **Exposure Calculation:** The system tracks the total value of borrowing power currently backed by a specific asset (e.g., $WBTC). * **Enforcement:** If the total exposure reaches the defined Quota Limit, the system blocks any transaction that would further increase exposure to that asset. * New Credit Accounts cannot be opened with that collateral. * Existing accounts cannot increase the amount of debt that is backed by particular token. * Repayments and closures remain enabled to allow deleveraging. This architecture ensures that even if a pool has abundant idle liquidity, it cannot be drained into a single illiquid or high-risk strategy beyond the safety parameters defined by the Curator. ## Quota Rates (Risk Premium) The Quota system decouples the cost of liquidity from the cost of risk. It allows the protocol to charge an additional interest rate—the **Quota Rate**—based specifically on the collateral held by the borrower. ### The Additive Rate Model The total cost of borrowing before fees is the sum of the base cost of capital and the specific risk premium of the collateral. $$ \text{Total APR} = \text{Base Rate} + \text{Quota Rate} $$ * **Base Rate:** Determined by the utilization of the Liquidity Pool. This represents the opportunity cost of the underlying asset (e.g., USDC). * **Quota Rate:** Determined by the specific collateral asset (e.g., a volatile governance token). This represents the risk premium for holding that specific asset. ### Pricing Granularity This separation allows for granular risk pricing within a single pool: * **Low-Risk Collateral:** Borrowers using blue-chip assets (e.g., WETH) may pay only the Base Rate (Quota Rate = 0%). * **High-Risk Collateral:** Borrowers using volatile or less liquid assets must pay the Base Rate plus a significant Quota Rate (e.g., +5%). This ensures that borrowers using safe collateral do not subsidize the risk of those using volatile collateral, improving capital efficiency for low-risk strategies while properly pricing tail risk. ### Learn More * **Base interest calculation:** How does pool utilization determine the underlying cost of capital? * [interest-rate-model](https://docs.gearbox.finance/core/interest-rate-model) * **Parameter configuration:** Who configures these limits and what parameter ranges are allowed? * [risk-configuration-dictionary](https://docs.gearbox.finance/core/risk-configuration-dictionary) * **Protocol fees:** How is interest revenue captured and shared between the Protocol DAO and the Market Curator? * [dao-and-curators-business-model](https://docs.gearbox.finance/core/dao-curators-business-model) ## Liquidation Dynamics Source: https://docs.gearbox.finance/core/liquidation-dynamics File: content/core/liquidation-dynamics.mdx The solvency of a Credit Account is determined deterministically on-chain. If an account's risk-adjusted value falls below its liabilities, the protocol enforces liquidation to protect liquidity providers. ## Solvency Definition: The Health Factor The core metric for solvency is the **Health Factor (HF)**. $$ HF = \frac{TWV}{Total Debt} $$ Where: * **TWV (Total Weighted Value):** The risk-adjusted, quota-limited value of the collateral assets, measured in the underlying token. * **Total Debt:** The total amount of underlying token owed, including principal, accrued interest, and quota interest. ### Total Weighted Value (TWV) TWV represents the maximum debt the current collateral portfolio can support. Unlike standard Net Asset Value, Gearbox discounts collateral based on its **Liquidation Threshold (LT)** and caps it by the **Quota** allocated to that asset. $$ TWV = \frac{\sum\_{i}^{MaxEnabledTokens}{\min{(Quota\_i, Balance\_i \times Price\_i \times LT\_i)}}}{Price\_{underlying}} $$ * **Quota\_i**: The specific portion of the account's debt limit allocated to token i. * **Balance\_i**: The balance of token i in the Credit Account. * **Price\_i**: The current oracle price of token i. * **LT\_i**: The Liquidation Threshold for token i. * **Price\_{underlying}**: The current oracle price of the underlying borrowed asset. > **Note:** The `min` function ensures that a specific collateral asset cannot secure more debt than its allocated Quota allows, regardless of its market value. ### Liquidation Condition An account is liquidatable if: 1. **HF < 1**: The TWV is less than the Total Debt. 2. **Expiration**: The Credit Manager has reached its maturity date (for fixed-term strategies). ## Partial Liquidation (Deleverage) To prevent total loss of user positions during minor market dips, the protocol supports **Partial Liquidation**. This mechanism sells only enough collateral to restore the Health Factor to a safe level, rather than closing the entire position. This process is typically executed by a specialized Deleverage Bot. ### Execution Logic When HF drops below a configured `minHF` (but is typically still > 1), the bot executes a deleveraging transaction: 1. Calculates the amount of collateral required to be sold to raise HF to `targetHF`. 2. Repays a portion of the debt. 3. Charges a reduced premium compared to full liquidation. ### Configuration Parameters | Parameter | Description | | ---------------- | --------------------------------------------------------------------------------------- | | **minHF** | The threshold triggering partial liquidation (e.g., 1.05). | | **maxHF** | The target Health Factor after deleveraging. | | **PremiumScale** | The percentage of the full Liquidation Premium charged (e.g., 50% of standard premium). | ## Full Liquidation If Partial Liquidation is insufficient or if HF drops significantly below 1, a **Full Liquidation** occurs. The liquidator repays the total debt and claims the collateral assets at a discount. ### Total Value Calculation Liquidation math relies on the **Total Value** of the account (undiscounted NAV), measured in the underlying token. $$ Total Value = \frac{\sum\_{i}^{MaxEnabledTokens}{Balance\_i \times Price\_i}}{Price\_{underlying}} $$ ### Liquidator Incentive The liquidator receives the collateral assets valued at a discount (the Liquidation Premium). $$ LiquidatorProfit = TotalValue \times LiquidationPremium - GasCost $$ ### Borrower Loss The borrower loses the collateral used to pay the debt, the premium, and the protocol fee. $$ AccountLoss = \min(TotalValue \times (LiquidationPremium + LiquidationFee), TotalValue - Total Debt) $$ * **Liquidation Premium:** Paid to the liquidator. * **Liquidation Fee:** Paid to the Protocol (Curator & DAO). ## Bad Debt & Socialization **Bad Debt** occurs when a Credit Account is liquidated while its **Total Value** is less than its **Total Debt**. ### Resolution Mechanism 1. **Fee Buffer:** Unclaimed protocol fees (Curator/DAO share) are burned to cover the deficit. 2. **Socialization:** If fees are insufficient, the remaining loss is socialized among Liquidity Providers by reducing the exchange rate of the Diesel Token (LP token). ### Learn More * **Data sources:** How does the protocol obtain asset prices for Total Weighted Value (TWV) calculations? * [price-oracle](https://docs.gearbox.finance/core/price-oracle) * **Parameter control:** Who sets liquidation thresholds (LT), premiums, and fees? * [risk-configuration-dictionary](https://docs.gearbox.finance/core/risk-configuration-dictionary) * **Quota mechanics:** How are quota limits defined and adjusted? * [quota-controls](https://docs.gearbox.finance/core/collateral-limits-specific-rates) ## Deleverage bot Source: https://docs.gearbox.finance/core/deleverage-bot File: content/core/deleverage-bot.mdx ## Deleverage - protection against liquidations The deleverage bot is designed to protect Gearbox users from full liquidations by automatically reducing leverage when an account’s health factor (HF) falls below a safe threshold. It acts as an early warning mechanism selling a small portion of collateral to restore safety before liquidation conditions are met. By doing so, the bot helps maintain protocol stability, safeguards user positions, and ensures smooth, market-driven deleveraging without requiring manual intervention or external subsidies. ## How to connect a bot Any user can connect a bot directly through the UI. From a technical standpoint, bot deployment is fully permissionless, users do not need approval from the DAO or a curator to deploy or connect a bot. However, for a bot to appear and be connectable via the UI, it must first be whitelisted there. ## Bot fees When a deleveraging event occurs, two types of fees are distributed: * **Premium:** Paid to the liquidator (deleverager) who executes the deleverage transaction. This serves as the direct incentive for running a bot and maintaining system safety. * **Fee:** Sent to the protocol treasury as the protocol’s share from the operation. ## Bot parameters | minHF | The threshold at which the bot starts deleveraging. When a user’s HF falls below this value, the bot begins selling part of their collateral to restore stability. | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | maxHF | The upper limit to which the bot is allowed to increase a user’s HF during a deleveraging operation. The bot will not push the HF above this value. The target HF for each operation lies somewhere between minHF and maxHF, depending on market conditions and the available liquidity. | | PremiumScale | Defines how much of the Credit Manager’s liquidation premium is taken as the deleverage premium. A value of 100% means the bot receives the same premium as a liquidator would. | | FeeScale | Specifies the fraction of the protocol fee applied to deleveraging. Typically set to 100%, aligning it with the standard liquidation fee. | ## **Rationale Behind Selecting Bot Parameters** ### **1. Primary Goal – Prevent Full Liquidations** The main purpose of the deleverage bot is to **protect users from full liquidations**. * The `minHF` (health factor at which deleverage is triggered) should be high enough so that a sudden drop in collateral value doesn’t make an account liquidatable immediately. * This gives the bot a time window to act and deleverage before liquidation occurs. * **Example:** If **WETH** is the collateral and we want to protect users from a **10% short-term price drop**, then: ``` minHF = 1 + 0.10 = 1.1 ``` *** ### **2. Avoid Triggering Under Normal Conditions** Deleveraging should **not** happen during ordinary market fluctuations. * Therefore, `minHF` should be **as low as possible**, ensuring that minor price deviations do not trigger unnecessary deleveraging. *** ### **3. Minimize Collateral Sold Per Event** The amount of collateral sold in a single deleveraging event should be minimized. * To achieve this, `maxHF` should be set **as close as possible to `minHF`**, limiting the size of each operation. *** ### **4. Ensure Organic Profitability** Deleveraging operations should be **naturally profitable** to encourage participation from external bots without requiring subsidies. * Set `PremiumScale` and `FeeScale` to **100%**, meaning the **deleverage premium = liquidation premium**. * The scale defines how much of the Credit Manager’s liquidation premium is allocated to deleveraging. * `maxHF` should be high enough so that both the **liquidation size** and **premium** are meaningful in dollar terms. *** ### **5. Keep Minimal Position Size Reasonable** The minimum position size (Credit Manager’s minimum debt) should not be too large. * The target for the **minimum position size** is around **$10,000**. ## Price Oracle Source: https://docs.gearbox.finance/core/price-oracle File: content/core/price-oracle.mdx The Price Oracle serves as the protocol's central valuation engine. Its primary function is to ingest raw price data from diverse external sources and standardize it into a uniform format that the Credit Manager and Pool contracts can consume mathematically. ## Data Normalization DeFi assets vary significantly in their technical specifications, particularly regarding decimal precision (e.g., USDC uses 6 decimals, WETH uses 18). To prevent calculation errors and complexity within the risk engine, the Price Oracle enforces a strict normalization standard. **The 8-Decimal Standard**\ Regardless of the underlying token's decimals or the external feed's native precision, the Gearbox Price Oracle always returns prices scaled to **8 decimals**. * **Input:** Raw data from Chainlink (8 decimals), Uniswap (18 decimals), or USDC (6 decimals). * **Process:** The Oracle wrapper scales the value up or down mathematically. * **Output:** A standardized USD price where `1.00` is represented as `100,000,000`. This uniformity allows the Credit Manager to perform solvency checks ($HealthFactor > 1$) using a single, consistent formula across all collateral types. ## Staleness Enforcement To ensure solvency calculations reflect current market reality, the Price Oracle enforces strict data freshness constraints. Every price feed is configured with a specific `stalenessPeriod` (measured in seconds), typically derived from the feed provider's heartbeat or update frequency. * **The Check:** Upon every transaction requiring a price (e.g., borrowing, liquidating), the Oracle compares the current `block.timestamp` against the feed's `updatedAt` timestamp. * **The Revert:** If `block.timestamp - updatedAt > stalenessPeriod`, the transaction reverts immediately. This mechanism prevents the protocol from accepting invalid collateral valuations or lending against stale prices during periods of oracle downtime or network congestion. ## Feed Types The protocol supports various data methodologies depending on the asset's liquidity profile and available onchain data. These are categorized into three primary mental models. ### 1. Spot Feeds Spot feeds provide the current market price based on off-chain aggregation or high-frequency on-chain updates. These are typically used for highly liquid "Blue Chip" assets where the price discovery happens on centralized exchanges or deep DEX pools. * **Push Models:** Traditional oracles where nodes push updates onchain at defined intervals or deviation thresholds (e.g., Chainlink, Redstone Push). * **Pull Models:** On-demand oracles where the price update is cryptographically signed off-chain and pushed onchain only when needed by a transaction (e.g., Pyth, Redstone Pull). This model reduces gas costs and allows for higher frequency updates. * **Use Case:** WETH, WBTC, USDC. ### 2. TWAP Feeds (Time-Weighted Average Price) TWAP feeds calculate the average price of an asset over a specific period (e.g., 30 minutes). This methodology dampens volatility and increases the cost of manipulation for assets that rely primarily on decentralized exchange liquidity. * **Mechanism:** Queries the cumulative price accumulator from an AMM (Automated Market Maker) and divides by the time elapsed. * **Use Case:** Curve LP Tokens, Pendle PTs, or long-tail assets where spot liquidity is thin. ### 3. Fundamental Feeds (Derived Value) Fundamental feeds determine value based on the on-chain backing or exchange rate of the asset, rather than secondary market trading activity. These feeds calculate what the asset is "worth" in terms of its underlying reserves. * **Mechanism:** Reads the `convertToAssets` or `getRate` function from the token contract and multiplies it by the underlying asset's USD price. * **Use Case:** ERC-4626 Vault Shares, Liquid Staking Tokens (LSTs), or Stablecoin peg-protection modules. ## Modular Pricing Architecture Beyond standard oracle integrations, Gearbox maintains a library of purpose-specific pricing contracts designed to collateralize complex DeFi positions. These modular feeds allow the protocol to support assets that lack direct secondary market feeds by programmatically deriving their value from the underlying protocol state: * **Curve & Balancer LPs:** Calculates the "Virtual Price" or fair value of the LP token based on the pool's invariant and the prices of the constituent tokens. * **Pendle PTs:** Derives the market price using a TWAP of the PT/SY exchange rate from the Pendle market contract. * **Bounded Feeds:** Wrappers that enforce upper or lower bounds on a price (e.g., capping a stablecoin at $1.00 or an LST at its backing ratio) to prevent manipulation during de-peg events. This architecture enables Curators to list productive assets (Vaults, LPs, Derivatives) as collateral without waiting for centralized oracle providers to support them. *** ### Learn More * **Safety & manipulation resistance:** How does the system protect against oracle manipulation and extreme market conditions? * [dual-oracle-system](https://docs.gearbox.finance/core/dual-oracle-system) ## Smart Oracles Source: https://docs.gearbox.finance/core/smart-oracles File: content/core/smart-oracles.mdx ## Safety-first design Gearbox oracle and solvency checks structure allows creating pricing methods with unique features: * Attract borrowers using hardcoded/ fundamental oracles + protect LPs by always taking market price into account.\ Read more: [dual-oracle-system](https://docs.gearbox.finance/core/dual-oracle-system) * Ensure timely liquidations using market oracles + protect LPs by always taking collateral fundamental value into account.\ Read more: [loss-policy](https://docs.gearbox.finance/core/loss-policy) ## Optimized for DeFi, scalable by default Gearbox supports major price feed providers, including Chainlink, Redstone (both pull and push models), and Pyth. Custom audited smart-contract feeds allow pricing of DeFi assets, including Pendle PT, Curve & Balancer LP tokens and more.\ Read more: [price-oracle](https://docs.gearbox.finance/core/price-oracle) ## Dual-Oracle System Source: https://docs.gearbox.finance/core/dual-oracle-system File: content/core/dual-oracle-system.mdx The Dual-Oracle System is the primary defense layer against price manipulation and oracle failure. By decoupling the valuation source used for liquidations from the source used for user operations, Gearbox ensures that short-term volatility or manipulation in one feed cannot be exploited to drain protocol liquidity. ## Dual-Feed Architecture Every asset in a Gearbox Market is configured with two independent price feeds. The protocol applies distinct logic to each feed depending on the context of the transaction. ### 1. Main Feed (Solvency & Liquidation) The **Main Feed** serves as the authoritative source for the system's internal accounting. * **Role:** Determines the Health Factor ($H\_f$) for liquidation triggers. * **Objective:** To reflect the asset's valuation for long-term solvency. ### 2. Reserve Feed (Safety & Operations) The **Reserve Feed** acts as a sanity check for user-initiated actions. * **Role:** Validates solvency during collateral withdrawals, debt increases, or complex multicall executions. * **Objective:** To prevent users from exploiting temporary price divergences to withdraw more collateral than they are entitled to. ## Pricing Methodologies To understand the utility of the Dual-Oracle system, one must first distinguish between the two primary methodologies for pricing DeFi assets. ### 1. Fundamental Price (Hardcoded / Backing Value) Prices the token based on the reserves that back it or its exchange rate (e.g., `1 stETH = 1 ETH` or `1 Stablecoin = $1`). | Stakeholder | Pros | Cons | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Borrowers** | Stability: Minimal risk of liquidation due to temporary market de-pegs. Accuracy: Reflects true staking appreciation immediately. | — | | **Lenders** | **Manipulation Resistance:** Immune to low-liquidity DEX manipulation. | Insolvency Risk: May overprice assets during real backing failures. Liquidity Lock: Funds may become stuck if the market price drops below the fundamental price, removing incentives for repayment. | ### 2. Secondary Market Price Prices the token based on buy/sell activity on DEXes or CEXes. | Stakeholder | Pros | Cons | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Borrowers** | — | Capital Inefficiency: Must maintain higher Health Factors to buffer against volatility. Liquidation Risk: Susceptible to cascading liquidations during market panic. | | **Lenders** | Pessimistic Pricing: Liquid tokens usually trade at a discount to backing, providing a safety buffer. Reactivity: Fast reaction to real market drops. | Manipulation Risk: Illiquid markets can be pumped to drain pool reserves at inflated valuations. Bad Debt: Liquidation cascades can lead to overselling collateral below debt value. | ## Comparison Logic: The "Safe Price" When a Credit Account executes a transaction that reduces its collateralization (e.g., withdrawing funds or borrowing more), the protocol calculates the account's value using the **Safe Price**. The Safe Price is derived dynamically for every asset in the portfolio: $$ P\_{Safe} = \min(P\_{Main}, P\_{Reserve}) $$ This `min()` logic creates an automatic circuit breaker. If the Main Feed and Reserve Feed diverge, the protocol enforces the lower (more pessimistic) valuation for all user operations, preventing the extraction of value during de-pegs or manipulation events. ## Scenario Analysis: The "Best of Both Worlds" By configuring the **Main Feed** as a Fundamental source and the **Reserve Feed** as a Market source, Gearbox protects lenders from manipulation while preserving capital efficiency for borrowers. The table below illustrates a scenario where a collateral token (e.g., sUSDe or deUSD) is used to borrow a stablecoin (USDC). | Scenario | Dual-Oracle System | Hardcoded Feed Only | Market Feed Only | | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Market price drops > 2.5% (Normal Volatility) | ✅ No Liquidations Main feed remains stable. | ✅ **No Liquidations** | ⚠️ Liquidations Triggered Risky positions are closed due to volatility. | | Market price drops > 10% (De-peg / Panic) | ⚠️ No Liquidations ✅ Withdrawals Blocked Safe Price uses the lower Market price ($0.90). Users cannot withdraw the "overvalued" asset, trapping liquidity in the protocol until solvency is resolved. | ⚠️ No Liquidations 🚨 Attack Vector: Attacker buys asset at $0.90, borrows $0.915 against it (at Face Value). Result: Protocol drained; Bad Debt created. | 🚨 Mass Liquidations Major portion of positions liquidated, potentially crashing price further. | | Market price pumps > 2.5% (Normal Volatility) | ✅ **No Liquidations** | ✅ **No Liquidations** | ✅ **No Liquidations** | | Market price pumps > 10% (Illiquid Market Manipulation) | ✅ No Liquidations ✅ Borrowing Blocked Safe Price uses the lower Fundamental price ($1.00). User cannot borrow against the inflated Market price ($1.10). | ✅ **No Liquidations** | ✅ No Liquidations 🚨 Attack Vector: Attacker mints asset at $1.00, pumps market to $1.10, borrows $1.02. Result: Protocol drained due to inflated valuation. | ## Circuit Breakers & Interaction Blocking The Dual-Oracle system enforces logic that effectively forbids interactions when data integrity is compromised. ### Transaction-Level Blocking The system does not require a global pause to stop exploits. It blocks individual transactions based on real-time data divergence: * **Withdrawal Block:** If $P\_{Main} \gg P\_{Reserve}$, the user's borrowing power is constrained by $P\_{Reserve}$. Users cannot withdraw funds based on the inflated Main price. * **Liquidation Protection:** Liquidations rely solely on the **Main Feed**. If the Main Feed is accurate but the Reserve Feed is broken/manipulated, liquidations can still proceed to keep the pool solvent, while user withdrawals (which require Reserve validation) are temporarily blocked to prevent capital flight. ### Divergence Thresholds While the protocol uses the `min()` logic continuously, significant divergence between Main and Reserve feeds serves as an off-chain signal for Risk Curators. * **Soft Breaker:** Small deviations are absorbed by the `min()` logic, simply reducing capital efficiency slightly. * **Hard Breaker:** Large deviations typically indicate a de-peg or oracle failure. In these scenarios, the `min()` logic effectively freezes new borrowing and withdrawals for that specific asset until the feeds converge or the Instance Owner updates the configuration. *** ### Learn More * **Bad debt handling:** How does the protocol handle bad debt if price safety mechanisms fail? * [loss-policy](https://docs.gearbox.finance/core/loss-policy) * **Price feed sources:** Where do the raw Main and Reserve price feeds originate? * [](https://docs.gearbox.finance/core/smart-oracles) ## Loss Policy Source: https://docs.gearbox.finance/core/loss-policy File: content/core/loss-policy.mdx ## The Problem: Market Price Cascades Using market oracles can sometimes trigger liquidation cascades, where a rapid price drop causes mass liquidations and further depresses the asset’s price. An example is the [ezETH cascading liquidations in April 2024](https://www.google.com/url?sa=E\&q=https%3A%2F%2Fprotos.com%2Fdepeg-of-3b-restaking-token-ezeth-causes-over-60m-in-defi-liquidations%2F). ![Figure](https://docs.gearbox.finance/assets/docs/core/loss-policy/01-the-problem-market-price-cascades.png) When prices fall too quickly, liquidators may be unable to react in time. As a result, positions can become insolvent before liquidation completes. In such scenarios, continuing to liquidate at the current market price may actually create bad debt, because collateral can be sold far below its fair or medium-term value. ## The Solution: Aliased Pricing To protect liquidity providers (LPs) in these situations, Gearbox implements a Loss Policy mechanism. **The logic is as follows:** 1. Positions are liquidated using market prices under normal conditions. 2. If a liquidation would create bad debt (Collateral Value < Debt), the protocol reprices the collateral using the **aliased price**, which can be configured to the asset’s fundamental value (e.g., Exchange Rate or 1.00 for stablecoins). 3. If the position is healthy under this fundamental pricing, the liquidation is halted. ![Figure](https://docs.gearbox.finance/assets/docs/core/loss-policy/02-loss-policy-protected-pool-flow.png) ## Execution Flow The Loss Policy acts as a conditional circuit breaker during the liquidation process. 1. **Standard Check:** Is Health Factor < 1 using the **Main Feed** (Market Price)? * **No:** Account is healthy. Do nothing. * **Yes:** Proceed to step 2. 2. **Bad Debt Check:** Does `Collateral Value < Debt`? * **No:** Liquidation proceeds normally. Liquidator repays debt and claims collateral. * **Yes:** The liquidation is flagged as a "Loss Liquidation". Proceed to step 3. 3. **Fundamental Check:** Is Health Factor < 1 using the **Aliased Feed** (Fundamental Price)? * **No:** The protocol assumes the market price is temporarily dislocated (flash crash). Liquidation is blocked to prevent realizing the loss at a distressed price. * **Yes:** The asset is fundamentally insolvent. Liquidation proceeds. ### Learn More * **Bad debt acknowledgment:** What happens when a liquidation proceeds under the Loss Policy and bad debt is realized? * [liquidation-dynamics](https://docs.gearbox.finance/core/liquidation-dynamics) ## DAO & Curators' business model Source: https://docs.gearbox.finance/core/dao-curators-business-model File: content/core/dao-curators-business-model.mdx ## Interest Fee (Revenue from Borrowing) The **Interest Fee** is the primary revenue source for the protocol and curators. It is a percentage markup applied to the borrowing interest paid by users. ### How It Works Unlike some protocols where the protocol fee is subtracted from the yield paid to liquidity providers (a “rake”), Gearbox uses an **additive model**. The fee is added on top of the base interest rate. * **Base & Collateral-specific Rate**\ The rate determined by the Interest Rate Model (IRM) plus any collateral-specific adjustments.\ \&#xNAN;*This portion is paid entirely to Liquidity Providers.* * **Interest Fee**\ A percentage markup applied to the Base Rate.\ \&#xNAN;*This portion is paid to the Market Curator and the Gearbox DAO.* ### Borrower Rate Formula $$ Rate\_{Borrower} = (Rate\_{Base} + Rate\_{Collateral-specific}) \times (1 + Fee\_{Interest}) $$ ### Example Calculation If market conditions dictate a base rate of **5%**, and the Curator has configured an Interest Fee of **20%**: 1. **Liquidity Providers earn:** 5.00% 2. **Protocol markup:** 5.00% x 20% = 1.00% 3. **Borrower pays:** 6.00% *** ## Revenue Split By default, all collected Interest Fees are split: * **50%** → Market Curator * **50%** → Gearbox DAO *** *** ## Liquidation Economics (Revenue from Risk) When a Credit Account becomes insolvent, it is liquidated. During liquidation, penalties are applied to the borrower for two purposes: * Incentivizing liquidators * Generating protocol revenue ### Components | Component | Recipient | Purpose | | ----------------------- | ------------- | -------------------------------------------------- | | **Liquidation Premium** | Liquidator | Incentive (“bounty”) for executing the liquidation | | **Liquidation Fee** | DAO & Curator | Protocol revenue from the liquidation | ## Insurance & Solvency Reserves Source: https://docs.gearbox.finance/core/insurance-solvency-reserves File: content/core/insurance-solvency-reserves.mdx The Gearbox Protocol employs an automated, on-chain reserve system designed to absorb bad debt and protect Passive Lenders. This mechanism functions not as an external insurance policy, but as a **retention buffer** on protocol revenue. Its primary objective is to ensure that the Liquidity Pool remains solvent even if a borrower's position is liquidated below the value of their debt. ## Conceptual Overview In traditional finance, this is analogous to a "First-Loss Capital" tranche. The protocol generates revenue through interest rates and liquidation fees. Rather than distributing 100% of this revenue to the DAO or Market Curators immediately, the system enforces a **mandatory savings threshold**. 1. **Revenue Accumulation:** All protocol fees flow into a specific contract (`TreasurySplitter`). 2. **The Safety Floor:** A target insurance amount is defined (e.g., 100,000 USDC). 3. **Conditional Distribution:** * **Below Target:** If reserves are below the target, **100% of revenue is retained**. No profit is distributed. * **Above Target:** Only the *excess* revenue (surplus) is distributed to the DAO and Curators. This ensures the protocol prioritizes solvency over profit extraction. *** ## Architecture: The Treasury Splitter The core component governing this logic is the `TreasurySplitter` contract. It acts as a gatekeeper between protocol fees and profit recipients. ### The Distribution Logic The `TreasurySplitter` holds assets (typically LP tokens of the pool it protects). When a distribution is attempted, the contract performs a logic check against the `tokenInsuranceAmount`. ### The Asset Composition The Insurance Fund does not sit idle. It is typically held in **LP Shares** (Diesel Tokens) of the pool it insures. This aligns the Treasury's interests with the Lenders' interests and allows the insurance capital to earn yield while waiting to be used. *** ## Bad Debt Coverage Mechanism "Bad Debt" occurs when a Credit Account is liquidated, but the collateral value is insufficient to repay the debt to the pool. Without insurance, this loss would be socialized among all Lenders (reducing the value of their LP tokens). The Insurance mechanism intervenes to prevent this socialization. ### The Coverage Flow 1. **Liquidation Event:** A liquidator closes a non-solvent Credit Account. The remaining collateral is sold, but a deficit remains (e.g., Debt: 100k, Collateral Value: 98k, Deficit: 2k). 2. **Loss Recognition:** The Credit Manager reports the loss to the Pool. 3. **Treasury Absorption:** The Pool burns **LP Shares held by the Treasury** equal to the value of the loss. By burning the Treasury's shares, the total supply of LP shares decreases, while the underlying assets in the pool remain (mostly) constant relative to the remaining Lenders. The Treasury effectively "pays" for the loss by giving up its claim on the pool's liquidity. *** ## On-Chain Verification Market participants can verify the solvency health of a pool by querying the `TreasurySplitter` contract directly. ### 1. Verify the Insurance Target (The Floor) To determine the minimum safety buffer the protocol enforces: * **Function:** `tokenInsuranceAmount(address token)` * **Interpretation:** This is the "water level." The protocol will not allow profit-taking if reserves drop below this value. ### 2. Verify Current Reserves (The Buffer) To determine the actual capital available to absorb losses: * **Function:** `IERC20(token).balanceOf(address treasurySplitter)` * **Interpretation:** * If `Balance > InsuranceAmount`: The pool is fully insured and generating surplus. * If `Balance < InsuranceAmount`: The pool is building reserves; all fees are currently being retained to increase safety. ### 3. Monitor Governance Changes Changes to insurance parameters require a dual-signature process (Curator + DAO). * **Function:** `activeProposals()` * **Interpretation:** Returns pending changes to the insurance floor or distribution logic. This allows Lenders to see if a Curator is attempting to lower safety parameters. *** ## Treasury-insured pools By default, all fees that the DAO receives from the protocol are made in dTokens. However, DAO can manage this by unwrapping part of the funds from the pools (thus, instead of dTokens, DAO will receive the usual underlying asset of the pool aka idle assets). This way, the DAO can limit its earnings from the Reserve Fund exposure. Essentially, the Gearbox dTokens inside this Fee Guard are the Insurance Fund. Anything that is not in dTokens has likely been voted to be unwrapped and kept as non Insurance Fund. Any non-dTokens are not counted towards the Insurance Fund size. And this only applies to V3 contracts. > > > This address holds all the fees accumulated. However, on the topic of the Reserve Fund, only look at the balances of dTokens. No other assets are relevant to the Reserve Fund. This Reserve Fund model doesn't relate to actual software hacks. It specifically covers liquidation shortfalls when collateral proceeds do not fully repay debt. ### Learn more ## Audits & Bug Bounty Source: https://docs.gearbox.finance/core/audits-bug-bounty File: content/core/audits-bug-bounty.mdx Keep in mind that no number of audits can guarantee full safety. There are always high risks involved in DeFi, as many platforms are composable and depend on each other. There is no guaranteed return on Gearbox - you must **understand the risks involved**. ## Audits ![Figure](https://docs.gearbox.finance/assets/docs/core/audits-bug-bounty/01-gearbox-protocol-gear-audits-abdk-chain-security-sigma-prime.png) Gearbox protocol and its modules have been audited multiple times by top-tier security teams. For the full up-to-date list of contracts and reports please refer to [Bytecode Repository](https://permissionless.gearbox.foundation/bytecode), which acts as a source of truth for verification of each deployed contract. *** ## Bug Bounty The scope of the bug bounty refers to these contracts: []() Rewards are distributed according to the impact of the vulnerability. The final decision on the payout amount will be determined by the Gearbox DAO developers at their discretion. | Severity | Payment in USDC / other stablecoin | | |---|---|---| | Low | $100 - $1K | | | Medium | $1K - $5K | | | High | $5K - $20K | | | Critical | $20K - $200K (+ GEAR) | | For all assets labeled as “Gearbox v1” or "Gearbox v2" and deployed on the Ethereum network, only Critical and High impacts are in-scope. If you have found a bug that you think is within the security interests of the protocol but is outside of the scope of the repository above, please do notify us then anyway. We can decide ad-hoc together with you. 1/1 payouts have been done before based on this. Join the Bug Bounty with Immunefi! Help Gearbox stay safe and be rewarded for it. ![Figure](https://docs.gearbox.finance/assets/docs/core/audits-bug-bounty/02-bug-bounty.png) https://immunefi.com/bounty/gearbox/ If you need more information on the protocol, please check: * Regular protocol docs: [/ ](/) * Developer docs: **NOTE**: for bugs related to the interface which are just referring to typos and non-security related issues, please feel free to report them in a community [Discord](https://discord.gg/5YuHH9tvms) pro bono - and Gearbox community can maybe send nice GIFs your way. In case a bug you found is related to the interface and is outside of the scope, but has serious security concerns, please do report it as well and a bounty can be also decided ad-hoc. Again, you can ask all your questions in [Discord](https://discord.gg/JZgvmaenwn). ### Rules Determinations of eligibility, score and all terms related to an award are at the sole and final discretion of Gearbox Protocol working DAO members. The goal is to make sure the ecosystem is safe, and that proper bug bounty work is rewarded well. In order to be considered for a reward, all bug reports must contain the following: * Description of suspected vulnerability * Steps to reproduce the issue so we can check it * Your name and/or colleagues if you wish to be later recognized * (Optional) A patch and/or suggestions to resolve the vulnerability The following activities are **prohibited** by bug bounty program: * Testing with mainnet or public testnet contracts: all testing should be done on private testnets * Any testing with pricing oracles or third party smart contracts * Attempting phishing or other social engineering attacks against our employees and/or customers * Any testing with third party systems and applications (e.g. browser extensions) as well as websites (e.g. SSO providers, advertising networks) * Any denial of service attacks * Automated testing of services that generates significant amounts of traffic * Public disclosure of an unpatched vulnerability in an embargoed bounty Security is a continuous effort which must always be following protocol growth. As a DAO, it is imperative to constantly dedicate ample resources to ensure safety of funds. ## Market Curators Source: https://docs.gearbox.finance/core/market-curators File: content/core/market-curators.mdx The **Market Curator** is the operator of a specific lending market instance. Unlike traditional asset managers who actively allocate capital, Gearbox Curators act as **Risk Parameter Managers**. They define the boundary conditions—such as Loan-to-Value ratios, interest rate curves, and allowed collateral—under which the market operates. This role is permissionless: any entity can deploy a Market Configurator and launch a lending business on top of the Gearbox Protocol. ## Operational Model: Parameters, Not Funds The Curator does not have custody of user funds. Instead, the Curator manages a set of smart contracts that enforce rules on how funds can be utilized. ![Figure](https://docs.gearbox.finance/assets/docs/core/market-curators/01-operational-model-parameters-not-funds.png) * **No Custody:** Curators cannot withdraw Liquidity Provider (LP) funds or seize Borrower collateral (except via standard liquidation mechanics). * **No Active Allocation:** Curators do not manually move funds between strategies. They set the *eligibility* rules (e.g., "Strategy A is allowed up to $10M debt"), and the protocol automatically manages the flow based on user demand. ## Role Architecture To balance operational agility with security, Curator powers are segregated into distinct roles. These are typically assigned to different multisigs or governance controllers depending on the Curator's internal structure. ### 1. The Administrator (Governance) The ultimate authority for the market. This address controls the **Market Configurator** contract. * **Capabilities:** Can modify all risk parameters (LTVs, Supply Caps, Interest Models, Fee Splits). * **Constraint:** All actions are subject to a mandatory **Timelock** (see below). ### 2. The Emergency Admin (Security) A specialized role designed for crisis response. It has a limited subset of powers that bypass the timelock to prevent bad debt or exploits. * **Capabilities:** * Pause contracts (freeze borrowing/withdrawals). * Set debt limits to zero (stop new borrowing). * Forbid specific adapters or tokens (stop exposure to risky assets). * **Constraint:** Cannot *increase* risk (e.g., cannot raise LTVs or debt limits). Can only restrict operations. ### 3. Operational Roles Granular roles for day-to-day maintenance without full administrative access. * **Pausable/Unpausable Admin:** Can freeze or unfreeze specific market contracts. * **Fee Multisig:** Designated recipient for accrued protocol fees. * **Emergency Liquidator:** Whitelisted address permitted to liquidate positions when the market is paused. ## Safety Constraints: The Timelock To protect users from malicious or erroneous parameter changes, the protocol enforces a **Time-Delayed Execution** model for the Administrator role. * **The Rule:** Any transaction that alters a risk parameter (e.g., changing LTV from 80% to 90%) must be queued in the Timelock contract for a minimum of **24 hours** before execution. * **The Purpose:** This delay guarantees that Lenders and Borrowers have sufficient time to audit pending changes and exit the market if they disagree with the new risk profile. ## Economic Model Curators monetize their markets by configuring specific fee parameters. These fees are programmatic and deducted automatically by the smart contracts. ### Revenue Sources 1. **Interest Fee:** A percentage of the interest paid by borrowers. This is added on top of the base rate paid to Lenders. 2. **Liquidation Fee:** A percentage of the collateral value seized during a liquidation event. ### Fee Sharing The Gearbox Protocol infrastructure takes a share of the revenue generated by Curators to sustain the DAO and core development. * **Default Split:** 50% to the Curator / 50% to the Protocol DAO. * **Configuration:** This split is enforced at the `TreasurySplitter` contract level. ### Learn More * **Parameter reference:** Where can I find a comprehensive dictionary of all configurable risk parameters and their constraints? * [risk-configuration-dictionary](https://docs.gearbox.finance/core/risk-configuration-dictionary) ## Instance Owner Source: https://docs.gearbox.finance/core/instance-owner File: content/core/instance-owner.mdx The Instance Owner is a chain-specific technical multisig responsible for maintaining the integrity of the local Gearbox deployment. It acts as a **technical gatekeeper**, ensuring that critical infrastructure, specifically the Price Feed Store, remains secure, verified, and consistent across networks. Unlike Market Curators, who manage financial risk parameters, the Instance Owner operates under a strict mandate of **business neutrality**. It does not assess the economic viability of assets or strategies but ensures the underlying data feeds function correctly. ## The Neutrality Principle Gearbox enforces a strict separation between **Technical Maintenance** and **Financial Risk Management**. * **Market Curators (Financial Layer):** Responsible for setting LTVs, interest rates, and supply caps. They bear the economic risk of their decisions. * **Instance Owner (Infrastructure Layer):** Responsible for verifying that a price feed contract is technically sound, correctly configured, and secure. The Instance Owner does not gatekeep assets based on quality or volatility. If a Curator wishes to list a volatile asset, the Instance Owner’s sole responsibility is to ensure the requested price feed (e.g., Chainlink, Redstone, or TWAP) is implemented correctly and added to the registry. This prevents technical misconfigurations—such as decimal errors or stale feed pointers—without interfering in the free market of credit strategies. ## Core Responsibilities ### Price Feed Store Management The primary function of the Instance Owner is the management of the **Price Feed Store**, the onchain registry of allowed price sources for a specific network. Before a Curator can list an asset in a Credit Manager, the asset and its corresponding price feed must be whitelisted in the Price Feed Store. The Instance Owner verifies: 1. **Contract Verification:** The feed contract is verified on the block explorer. 2. **Source Integrity:** The feed points to the correct aggregator address (e.g., the official Chainlink or Pyth contract for that chain). 3. **Technical Specification:** The feed returns data in the format required by the Credit Manager (typically 8 decimals). Once verified, the Instance Owner adds the feed to the store, making it available for any Curator to use. * [**See: Price Oracle Architecture**](https://www.google.com/url?sa=E\&q=..%2Feconomics-and-risk%2Fprice-oracle.md) ### Protocol Upgrades & Maintenance While the Protocol DAO votes on global upgrades and new contract versions, the Instance Owner executes the specific transactions required to apply these updates to the local chain instance. This ensures that upgrades are applied atomically and correctly within the context of the specific network environment. ## Multisig Composition To maintain neutrality and prevent censorship, the Instance Owner multisig is composed of a diverse set of ecosystem participants. This structure ensures that no single entity can block a valid technical integration. **Typical Composition:** * **Threshold:** 4-of-12 (Subject to chain-specific configuration) * **Signers:** * Active Market Curators * Chain Foundation Contributors * Security Auditors * Partner Protocol Founders * Gearbox Core Contributors This broad distribution prevents the Instance Owner from becoming a point of centralization while maintaining a high bar for technical competence among signers. ![Figure](https://docs.gearbox.finance/assets/docs/core/instance-owner/01-credit-configurator-graph.png) ## Protocol DAO Source: https://docs.gearbox.finance/core/protocol-dao File: content/core/protocol-dao.mdx Unlike traditional DeFi protocols where the DAO manages risk parameters (like LTVs or Interest Rates) directly, Gearbox delegates these operational responsibilities to **Market Curators**. The DAO focuses on building the rails, while Curators operate the trains. ## Core Responsibilities ### 1. System Upgrades & Versioning The DAO maintains the core smart contracts that define the protocol's logic. It is the only entity capable of authorizing new versions of system components. * **Contract Updates:** The DAO votes to deploy and authorize new implementations of core contracts (e.g., `PoolV3`, `CreditManagerV3`). * **Bytecode Repository:** The DAO manages the onchain registry of verified contract bytecode. This ensures that when Curators deploy new markets, they are using secure, audited code approved by the protocol. ### 2. Chain Activation The DAO controls the expansion of the protocol to new blockchain networks. * **Instance Deployment:** Before Gearbox can operate on a new chain (e.g., Arbitrum, Optimism), the DAO must authorize the deployment of the **Instance Owner** and **Treasury** contracts on that network. * **Canonical Addressing:** The DAO ensures that there is a single, canonical instance of the protocol infrastructure on each supported chain, preventing fragmentation. ### 3. Economic Alignment (GEAR Token) The DAO utilizes the GEAR token to incentivize growth and align the interests of Curators, Liquidity Providers (LPs), and the protocol. * **Incentive Programs:** The DAO can vote to allocate GEAR tokens for liquidity mining or grants to bootstrap specific markets or integrations. * **Fee Split Configuration:** While Curators set the total fees for their markets, the DAO defines the protocol-level **Fee Split** (e.g., 50/50 split between Curator and DAO). Changing this global parameter requires a DAO vote. ## Limits of Authority To preserve the permissionless nature of the protocol, the DAO's power is strictly limited at the smart contract level. * **No Market Interference:** The DAO **cannot** change the risk parameters (LTVs, Liquidation Thresholds, Interest Rates) of a live market managed by a Curator. * **No Asset Management:** The DAO **cannot** seize or reallocate funds deposited into Curator-managed pools. This separation of powers ensures that Curators retain full sovereignty over their lending businesses. ### Learn More * **Risk management & operations:** Who manages risk parameters and oversees day-to-day market operations? * [market-curators](https://docs.gearbox.finance/core/market-curators) ## Protocol audits Source: https://docs.gearbox.finance/core/protocol-audits File: content/core/protocol-audits.mdx The **Bytecode Repository** is a core infrastructure component of Gearbox V3 designed to enable permissionless, multi-chain protocol expansion while maintaining strict security guarantees. It serves as a decentralized, on-chain registry for verified smart contract implementations. ## An On-Chain "GitHub" for Smart Contracts The Bytecode Repository acts as a decentralized version of a code hosting platform like GitHub, but for compiled EVM bytecode rather than source code. * **Versioned Catalog:** Like a GitHub repository with tags, it organizes contracts into **Domains** (e.g., `IRM` for interest rate models) and **Postfixes** (e.g., `_LINEAR`), allowing for semantic versioning (Major/Minor/Patch). * **Public vs. System Domains:** * **System Domains** (Core contracts like Credit Managers) are DAO-governed; updates require an on-chain vote. * **Public Domains** allow any developer to submit "plugins" (e.g., a new yield farming adapter). Once a developer's submission is verified, they "own" that identifier in the repository. * **Immutable Storage:** Instead of a centralized server, the contract uses **SSTORE2** to store the initialization code (init code) directly in the Ethereum state, ensuring it can never be deleted or modified. ## Protecting the Protocol Lifecycle The repository protects the protocol by decoupling the **upload** of code from its **deployment**, introducing a mandatory verification layer. ### 1. On-Chain Audit Verification Before a contract can be deployed via the repository, it must be "audited" on-chain. This is not just a social claim; it is a cryptographic requirement: * **Approved Auditors:** The Gearbox DAO maintains a whitelist of approved auditor addresses in the `BytecodeRepository`. * **EIP-712 Attestations:** Auditors sign a specific `bytecodeHash`. This signature is submitted to the repository via `submitAuditReport`. * **Enforced Solvency:** The `deploy` function checks `isBytecodeAudited`. If a bytecode hash does not have a valid signature from an authorized auditor, the protocol will refuse to deploy it, preventing unverified or malicious code from entering the ecosystem. ### 2. Deterministic and Secure Deployment The repository uses `CREATE2` to ensure that a contract deployed on Ethereum Mainnet will have the exact same address and code when deployed on L2s like Optimism or Arbitrum. * **Front-running Protection:** It mixes the deployer's address into the salt, preventing malicious actors from "sniping" a contract address before the legitimate user. * **Integrity Checks:** Upon deployment, the repository verifies that the resulting contract's `contractType` and `version` (via the `IVersion` interface) match the registry records. ## Key Security Features * **Init Code Blacklisting:** The DAO can permanently forbid specific `initCode` hashes (via `forbidInitCode`) if a vulnerability is found, effectively "bricking" that version and preventing any further deployments of it. * **Author Signatures:** Only the original author of the bytecode can upload it on Mainnet, preventing others from claiming ownership of a developer's work. * **Token-Specific Logic:** It handles edge cases (like USDT's non-standard transfer behavior) through `tokenSpecificPostfixes`, ensuring the correct specialized implementation is used for specific assets.
Sources * [contracts/global/BytecodeRepository.sol](https://github.com/Gearbox-protocol/permissionless/blob/master/contracts/global/BytecodeRepository.sol) * [specification.md](https://github.com/Gearbox-protocol/permissionless/blob/master/specification.md) * [contracts/interfaces/IBytecodeRepository.sol](https://github.com/Gearbox-protocol/permissionless/blob/master/contracts/interfaces/IBytecodeRepository.sol) * [contracts/traits/DeployerTrait.sol](https://github.com/Gearbox-protocol/permissionless/blob/master/contracts/traits/DeployerTrait.sol) * [script/UploadBytecode.s.sol](https://github.com/Gearbox-protocol/periphery-v3/blob/main/script/UploadBytecode.s.sol)
## V3.0 operational multisigs Source: https://docs.gearbox.finance/core/v3-0-operational-multisigs File: content/core/v3-0-operational-multisigs.mdx Multisig roles were split into a financial-treasury and technical. Both multisigs were created prior to the deployment ceremony by previous initial core members, as contracts needed to know the wallet addresses. Then, multisig members and a signer count requirement were added after **DAO voting procedures**. All this can be verified on-chain and Etherscan in logs of respective contracts. Multisig must execute whatever proposal reaches winning quorum. Given that multisig are members previously enacted by token holders, meaning the DAO, and are semi-public people with big reputation - in *extreme* cases they could voice against implementing some proposal. However, that could breach *trust* in the governance model and require immediate action and restructuring. This must be exercised carefully. ## Technical Guard | 6/12 Executes proposals which have reached quorum related to technical changes and the protocol. Ethereum Address: [0xA7D5DDc1b8557914F158076b228AA91eF613f1D5](https://etherscan.io/address/0xA7D5DDc1b8557914F158076b228AA91eF613f1D5) List of members on the multisig: 1. [zefram.eth](https://twitter.com/boredGenius) - Building [88mphapp](https://twitter.com/88mphapp), sudoswap, and more. Member of MetaCartel. 2. [Ignacio](https://twitter.com/iicc_eth) - Co-Founder of Stakely 3. van0k - Gearbox protocol developer 4. [0xmikko](https://twitter.com/0xmikko_eth) - original inventor of Gearbox \[on behalf of Gearbox Protocol Limited] 5. [Alex Smirnov](https://twitter.com/AlexSmirnov__) - co-founder of [deBridge](https://twitter.com/deBridgeFinance) 6. [MacLane Wilkison](https://twitter.com/MacLaneWilkison) - co-founder of [NuCypher](https://twitter.com/NuCypher) & [Threshold](https://twitter.com/TheTNetwork) 7. [Simone](https://twitter.com/kronosimste) - developer at [DegenScore](https://twitter.com/DegenScore) 8. [Lewi](https://twitter.com/lewifree) - OG degenerate & ESD summoner 9. [Klim](https://twitter.com/milkyklim) - data analytics and [YFI](https://twitter.com/iearnfinance) Maximalist 10. Alex - ex-Neutrino, a lobster and a builder 11. [Alex](https://twitter.com/0xAlexEuler) - CTO of [Mellow Protocol](https://twitter.com/Mellowprotocol) 12. [Lekhovitsky](https://twitter.com/lekhovitsky) - Gearbox protocol developer Transactions related to technical changes and protocol improvements are behind a 2-day timelock, and you can transparently observe every stage and queue in the [Risk Framework](https://risk.gearbox.foundation/updates): []() ### Veto / Unpause role | 4/12 Ethereum Address: [0xbb803559B4D58b75E12dd74641AB955e8B0Df40E](https://etherscan.io/address/0xbb803559B4D58b75E12dd74641AB955e8B0Df40E) A multisig with the same set of singers as the Technical Guard, but a lower 4/12 for faster response. The veto role is related to the ability to circumvent malicious proposals and transactions, it can only say "no" basically, but can't propose or push anything. The unpause role relates to unpausing. The pause function was granted to [2 analytical addresses](https://gov.gearbox.fi/t/gip-17-multisig-reshuffle-pausable-admin/1447) 1/1. They can only pause the protocol, in case their monitoring tools detect issues, in an attempt to stop the protocol from being fully exploited. In case that is possible and the time onchain gives that window. * 0xD5C96E5c1E1C84dFD293473fC195BbE7FC8E4840 * 0x65b384cecb12527da51d52f15b4140ed7fad7308 *** ## Treasury Guard | 5/10 Executes proposals which have reached quorum related to spending, grants, and the treasury overall. Ethereum Address: [0x7b065Fcb0760dF0CEA8CFd144e08554F3CeA73D1](https://etherscan.io/address/0x7b065Fcb0760dF0CEA8CFd144e08554F3CeA73D1) List of members on the multisig: 1. [Stani](https://twitter.com/StaniKulechov) - founder of [Aave](https://twitter.com/AaveAave), venture partner at [Variant Fund](https://twitter.com/VariantFund) 2. [Amplice](https://twitter.com/astr0bas3d) - [lobsterdao](https://twitter.com/10b57e6da0) member & core DAO contributor on marketing 3. [Pepo](https://twitter.com/0xPEPO) - contributor of [Wonderland](https://twitter.com/defi_wonderland) & [DeFi LATAM](https://twitter.com/defi_latam) 4. [Sergey](https://t.me/icodrops_sergey) - founder of [ICODrops](https://twitter.com/ICODrops) 5. [NDW](https://twitter.com/cryptondee) - Castle Capital member and a DeFi degen 6. [apeir99n](https://twitter.com/apeir99n) - original math & product at Gearbox \[on behalf of Gearbox Protocol Limited] 7. [Nikitakle](https://twitter.com/NOstroymov) - core DAO contributor on marketing & community 8. [Amantay](https://twitter.com/amantay_a) - core DAO contributor on risk & analytics 9. [duckdegen.eth](https://twitter.com/DuckDegen) - devrel, ex-Connext \[[GIP-40](https://gov.gearbox.fi/t/gip-40-financial-multisig-reshuffle/2204/5)] 10. [Vadym](https://twitter.com/0x_vadym) - head of product at Kolibrio Spending and grants paid out can be seen in monthly DAO reports: []() ### Fee Temporary Guard 5/10 Ethereum Address: [0x3E965117A51186e41c2BB58b729A1e518A715e5F](https://etherscan.io/address/0x3E965117A51186e41c2BB58b729A1e518A715e5F) A temporary multisig with the same set of singers as the Treasury Guard. It is created to separate funds from the DAO rounds which are used for the development of the protocol. This Fee Guard collects all fees from the protocol and can later on give control over to an initiative which will focus on staking programs, or whatever else the DAO decides to do. It's a holder of fees for now. ### Rewards management Guard 2/3 Executes rewards distribution and sets up temporary incentive campaigns, typically provided by partner protocols. Ethereum address: [0x6f378f36899cEB7C6fB7D293aAE1ca86B0Edbf6D](https://app.safe.global/transactions/history?safe=eth:0x6f378f36899cEB7C6fB7D293aAE1ca86B0Edbf6D) ## Risk Configuration Dictionary Source: https://docs.gearbox.finance/core/risk-configuration-dictionary File: content/core/risk-configuration-dictionary.mdx Flexibility is at the core of Gearbox’s design. Credit Accounts support a wide range of on-chain assets as collateral, which requires a risk framework capable of handling diverse asset properties. Gearbox’s risk controls are built to operate under uncertainty and adapt to any market conditions. Gearbox is a platform for the permissionless creation and curation of lending markets. To participate safely, both Curators and Users must understand the risk-control allowlist: Curators need to know the capabilities it grants, while Users should understand the trust assumptions they accept when engaging in lending activity. ## Curator Roles The Curator utilizes two primary roles to modify market parameters: * **Admin**\ Can modify all configurable parameters, subject to a minimum **24-hour timelock**. * **Emergency Admin**\ Can update a limited set of risk parameters **instantly** (without timelock) to mitigate immediate threats. ## Pool-Level Rules These parameters define the global constraints for the Liquidity Pool. If a user disagrees with these terms, they must select a different pool. ### Pool parameter definitions * **Total debt limit:** Maximum amount of underlying assets that can be borrowed across the entire pool. * **Collateral limit:** Maximum amount of debt that can be backed by a specific collateral token (Quota Limit). * **Main Price Feed:** Primary price source used for calculating account value and triggering liquidations. * **Reserve Price Feed:** Secondary price source used to run safety checks on operations; can block Credit Account actions to protect LPs. * **Increase Rate:** One-time fee charged whenever exposure to a collateral increases. * **Collateral-specific rate:** Additional interest rate (APR) charged for borrowing against a specific collateral. * **IRM:** The Utilization-based Interest Rate Model contract. * **Loss Policy:** The logic executed when a liquidation results in bad debt. * **Emergency liquidators whitelist:** Addresses authorized to liquidate accounts when the Credit Manager is paused (Default: Permissionless). * **Loss liquidators whitelist:** Addresses authorized to execute liquidations that result in bad debt (Default: Permissionless). ### Pool permissions matrix | Parameter | Admin (24h Delay) | Emergency Admin (Instant) | | ----------------------------------- | :---------------: | ------------------------- | | **Total debt limit** | ✅ | ⚠️ Reduce to zero-only | | **Collateral limit** | ✅ | ⚠️ Reduce to zero-only | | **Main Price Feed** | ✅ | ⚠️ Limited choice | | **Loss Policy** | ✅ | ⚠️ Can turn off | | **Loss liquidators whitelist** | ✅ | ⚠️ Can turn off | | **Emergency liquidators whitelist** | ✅ | ⚠️ Can turn off | | **Reserve Price Feed** | ✅ | ❌ | | **Increase Rate** | ✅ | ❌ | | **Collateral-specific rate** | ✅ | ❌ | | **IRM** | ✅ | ❌ | ## Credit Manager-Level Rules These parameters define the strategy for a specific Credit Manager. If a user disagrees with these terms, they can choose another Credit Manager within the same pool. ### Credit Manager parameter definitions * **Total debt limit:** Maximum aggregate debt of all Credit Accounts created from this Credit Manager. * **MinDebt:** Minimum required debt to open a Credit Account. * **MaxDebt:** Maximum permitted debt per Credit Account. * **Liquidation Premium:** Percentage of collateral value paid to the liquidator as an incentive. * **Liquidation Fee:** Percentage of collateral value paid to the Protocol (Curator & DAO). * **Max Enabled Tokens:** Maximum number of collateral tokens a single account can enable simultaneously. * **Interest Fee:** Percentage of borrowing interest captured as revenue (split between Curator & DAO). * **Collateral's LT:** The Liquidation Threshold (Loan-to-Value ratio). * **Collateral's forbidden status:** Controls whether a token is allowed or forbidden. * **List of allowed adapters:** Restricts which external contracts (e.g., Uniswap, Curve) a Credit Account can interact with. * **Expiration Policy:** Date after which the strategy winds down. After this date, all Credit Accounts become liquidatable regardless of Health Factor. ### Credit Manager permissions matrix | Parameter | Admin (24h Delay) | Emergency Admin (Instant) | | ---------------------------- | :---------------: | ------------------------- | | **Total debt limit** | ✅ | ⚠️ Reduce to zero-only | | **List of allowed adapters** | ✅ | ⚠️ Forbid-only | | **Collaterals list** | ✅ | ⚠️ Forbid-only | | **Liquidation Premium** | ✅ | ❌ | | **Liquidation Fee** | ✅ | ❌ | | **Collaterals' LT** | ✅ | ❌ | | **Expiration Policy** | ✅ | ❌ | | **MinDebt** | ❌ | ❌ | | **MaxDebt** | ❌ | ❌ | | **Max Enabled Tokens** | ❌ | ❌ | | **Interest Fee** | ❌ | ❌ | ## Usecase: Direct Redemptions Source: https://docs.gearbox.finance/core/usecase-direct-redemptions File: content/core/usecase-direct-redemptions.mdx ## The problem: constrained instant liquidity ⇒ leverage stops working properly Other lending protocols must treat assets with timelocked liquidity like standard tokens and rely on DEX liquidity to enable leverage. Building and maintaining deep DEX liquidity is hard, leading to thin books and low collateral limits. Furthermore, asset issuers often have to pay to seed and maintain DEX liquidity. **This leads to fragmented UX and capital-inefficiency**, forcing users to wait for weeks or pay months worth of yield for instant liquidity ![Figure](https://docs.gearbox.finance/assets/docs/core/usecase-direct-redemptions/01-problem-constrained-instant-liquidity-leverage-stops-working-properly.png) ## Gearbox's Solution **Zero DEX Liquidity Required:** With Gearbox, leverage can go live on day one. It eliminates the need for DEX liquidity seeding, working at any size. **Direct Integration:** Execution is handled through direct smart-contract integration, allowing deposits and withdrawals at face value. **Benefits for users:** * Save time up to **8 periods** of native redemption. * Capital requirements are reduced by **10x**. * Save fees equal to a **month of farming yield**. ## How it works For simplicity, we refer to the example semi-liquid asset as xVAULT, since vaults are a common example of assets with these properties. The same logic also applies to RWAs, LRTs, and other tokens with time-locked liquidity. ![Figure](https://docs.gearbox.finance/assets/docs/core/usecase-direct-redemptions/02-how-it-works.png) ### Take leverage * User adds USDC to Credit Account and borrows 5x more to get leveraged exposure on xVAULT yield * Credit Account deposits 6x USDC to xVAULT issuance contract and receives the xVAULT ### Undwind position * The Credit Account holds an xVAULT token and has an outstanding USDC debt. * The user starts the redemption process: Credit Account sends the xVAULT token to the redemption contract. * In return, the Credit Account receives a redemption receipt token, which represents a future claim on the underlying asset. * The Credit Account now holds the redemption receipt token and USDC debt. #### After the Redemption Window: * Once the redemption window has passed, the user can finalize the redemption. * The Credit Account burns the redemption receipt token and receives USDC to repay debt. The Credit Account always stays overcollateralized, while collateral transfroms from xRWA into redemption receipt token and eventually into liquid underlying. # Developer documentation SDK, contracts, Credit Accounts, multicalls, market data, integrations, deployment addresses, and automation guides. ## SDK Setup Source: https://docs.gearbox.finance/developers/sdk-setup File: content/developers/sdk-setup.mdx Connect the Gearbox SDK once when your TypeScript process starts, then reuse the attached instance for pool, account, and liquidation operations. ## Install ```bash npm install @gearbox-protocol/sdk viem dotenv ``` ## Preview SDK Some integration guides use APIs that are available in the SDK `next` release channel but have not reached the stable release. Pages that require it are marked **Preview SDK**. To test those integrations now, install: ```bash npm install @gearbox-protocol/sdk@next viem dotenv ``` Use the stable package unless a guide specifically requires the preview SDK. The preview requirement will be removed when the APIs reach the stable release. ## Configure For local development, create a file named `.env` in the project root: ```dotenv GEARBOX_NETWORK=Mainnet RPC_URL=https://your-rpc.example ``` The `dotenv` package loads these values into `process.env`. Do not commit `.env`. In production, provide the same variables through your deployment platform or secret manager. ## Attach Create a shared module such as `gearbox.ts`: ```typescript import "dotenv/config"; import { NetworkType, OnchainSDK } from "@gearbox-protocol/sdk"; const rpcUrl = process.env.RPC_URL!; const network = NetworkType.parse( process.env.GEARBOX_NETWORK ?? "Mainnet", ); export const sdk = new OnchainSDK(network, { rpcURLs: [rpcUrl], timeout: 30_000, retryCount: 2, }); await sdk.attach(); ``` `attach()` discovers the Gearbox markets and contracts for the selected network. Wait for it to complete before calling SDK features, and reuse the resulting `sdk` instance instead of attaching again for each operation. SDK-based integration guides assume this step is complete and import the shared instance: ```typescript import { sdk } from "./gearbox"; ``` ## Source - [Gearbox SDK](https://github.com/Gearbox-protocol/sdk) ## Lender (Pools) Source: https://docs.gearbox.finance/developers/lending File: content/developers/lending.mdx This section explains how to integrate programmatically with Gearbox pools. ## Overview Lenders provide the pool's underlying asset and receive ERC-4626 pool shares. Interest paid by borrowers increases the amount of underlying represented by those shares over time. ## What's in This Section | Page | Covers | | --- | --- | | [Pool Integration](https://docs.gearbox.finance/developers/pool-integration) | Deposit any pool underlying, withdraw it, check limits, and price pool shares | | [Obtaining RWA Underlying](https://docs.gearbox.finance/developers/obtain-rwa-underlying) | Mint or redeem `DefaultRWAUnderlying` when it is the asset accepted by a pool | ## Liquidations Source: https://docs.gearbox.finance/developers/liquidations File: content/developers/liquidations.mdx Liquidations repay debt from an unhealthy or expired Credit Account. This page explains when liquidation is possible and routes liquidators through the execution flow. ## When an account is liquidatable An account can be liquidated when: - its health factor is below `1.0`; or - its configured Credit Facade expiration has passed and the account still has debt. ### Full liquidation A full liquidation lets the liquidator buy the account's complete collateral portfolio at a discount. All debt is settled and the Credit Account closes. See [Full Liquidation](https://docs.gearbox.finance/developers/full-liquidation) for execution details. The standard entrypoints are permissionless while the Credit Facade is active. If it is paused, only an approved emergency liquidator can execute them. Loss-policy and asset-specific eligibility checks can also apply. If a full liquidation transfers pending redemption positions, continue with [Delayed Redemptions Liquidation](https://docs.gearbox.finance/developers/delayed-redemptions) for redeemer monitoring and claims. ## Recommended flow 1. **Discover accounts** that are unhealthy or expired. 2. **Inspect the exact outcome**, including the underlying amount to pay and the collateral to receive. 3. **Obtain the execution requirements**: the optional approval and unsigned liquidation transaction. 4. **Pass them to the operator's transaction pipeline** for simulation, signing, and submission. Continue with [Full Liquidation](https://docs.gearbox.finance/developers/full-liquidation). ## Full Liquidation Source: https://docs.gearbox.finance/developers/full-liquidation File: content/developers/full-liquidation.mdx > **⚠ Preview SDK** > > This guide requires the SDK `next` release channel. [Install the preview > SDK](https://docs.gearbox.finance/developers/sdk-setup#preview-sdk) before using these APIs. A full liquidation is a purchase of a Credit Account's complete collateral portfolio at the liquidation discount. ```text required underlying = total collateral value × liquidation discount ``` The transaction sends that underlying from the liquidator to the Credit Account, transfers the account's enabled collateral balances to the liquidator, settles the debt, and closes the account. This guide covers the Gearbox-specific steps for one liquidation attempt: find candidates, inspect one candidate, and obtain the execution payload. Before continuing, [install and attach the Gearbox SDK](https://docs.gearbox.finance/developers/sdk-setup). The caller supplies these inputs: | Variable | Type | Meaning | |---|---|---| | `sdk` | `OnchainSDK` | Attached Gearbox SDK instance | | `liquidator` | `Address` | Address that will pay for the liquidation and receive its outputs | | `supportedMainCollateral` | `Address[]` | Main collateral assets used to shortlist accounts | | `supportedRepaymentTokens` | `Address[]` | Tokens the liquidator is willing to pay | ## 1. Find liquidatable accounts `getLiquidatableAccounts()` returns unhealthy accounts and expired accounts with debt. Each result includes its `creditAccount` address, so no separate address discovery is required. ```typescript import { isAddressEqual } from "viem"; const collateralCandidates = await sdk.liquidations.getLiquidatableAccounts({ assets: supportedMainCollateral, }); const candidates = collateralCandidates.filter(candidate => supportedRepaymentTokens.some(token => isAddressEqual(token, candidate.repaymentAmount.token), ), ); ``` `candidates` is a `LiquidatableAccount[]`. Each `candidate` contains: | Field | Type | Meaning | |---|---|---| | `creditAccount` | `Address` | Credit Account to inspect or liquidate | | `creditManager` | `Address` | Credit Manager in which the account is opened | | `network` | `NetworkType` | Network on which the account exists | | `asset` | `Address` | Main collateral asset used for discovery filtering | | `totalValue.token` | `Address` | Token in which the account value is expressed | | `totalValue.balance` | `bigint` | Estimated account value in that token's native decimals | | `totalValueUSD` | `bigint` | Estimated account value in USD with 8 decimals | | `repaymentAmount.token` | `Address` | Estimated payment token | | `repaymentAmount.balance` | `bigint` | Estimated payment amount in that token's native decimals | | `estimatedProfit.token` | `Address` | Token in which gross profit is estimated | | `estimatedProfit.balance` | `bigint` | Gross profit estimate before gas and funding costs | | `isDelayed` | `boolean` | Whether the account contains delayed-redemption collateral | | `paused` | `boolean` | Whether its Credit Facade is paused | `assets` matches only `candidate.asset`, the account's main collateral. Use `details.receivedAssets` to validate the complete collateral portfolio. Candidate amounts are discovery estimates; use `getLiquidationDetails()` for the exact selected liquidation path before execution. ## 2. Inspect one candidate Choose one `candidate` from the filtered `candidates` list. `creditAccount` is the address of that candidate's Credit Account, and `details` is its fresh liquidation preview for the supplied `liquidator`: ```typescript const candidate = candidates[0]; if (!candidate) throw new Error("No supported liquidation candidates"); const creditAccount = candidate.creditAccount; const details = await sdk.liquidations.getLiquidationDetails({ creditAccount, liquidator, }); if (details.paused) throw new Error("Credit Facade is paused"); if (details.isCreditAccountFrozen) throw new Error("Credit Account is frozen"); if (!details.isLiquidatorEligible) { throw new Error(`Liquidator is not eligible for ${details.kycProtocol}`); } if ( !supportedRepaymentTokens.some(token => isAddressEqual(token, details.repaymentAmount.token), ) ) { throw new Error("Unsupported payment token"); } ``` `buildLiquidationTx()` can be called without this step, but `details` is the pre-execution preview. Use it to verify the approval, exact payment, complete received-asset list, and eligibility before execution. `details` is a preview, not a transaction: | Field | Type | Meaning | |---|---|---| | `repaymentAmount.token` | `Address` | ERC-20 the liquidator pays | | `repaymentAmount.balance` | `bigint` | Exact payment amount in that token's native decimals | | `receivedAssets` | `ReceivedAsset[]` | Complete list of immediate and delayed outputs | | `receivedAssets[].isDelayed` | `boolean` | Whether this output settles after the liquidation transaction | | `receivedAssets[].token` | `Address` | ERC-20 the liquidator receives now or after settlement | | `receivedAssets[].amount` | `bigint` | Immediate amount, or exact/estimated delayed amount, in native decimals | | `receivedAssets[].redeemerAddress` | `Address \| undefined` | Redeemer assigned to the liquidator for a delayed output | | `receivedAssets[].claimableAt` | `bigint \| undefined` | Estimated settlement time; `undefined` means the output is immediate or claimable now | | `approve.token` | `Address` | ERC-20 that must be approved, when approval is required | | `approve.spender` | `Address` | Exact contract address that receives the allowance | | `approve.amount` | `bigint` | Required allowance with the SDK's execution buffer | | `estimatedProfit.token` | `Address` | Token in which gross profit is estimated | | `estimatedProfit.balance` | `bigint` | Gross profit estimate before gas and funding costs, in the token's native decimals | | `isLiquidatorEligible` | `boolean` | Whether this wallet may receive restricted assets | | `isCreditAccountFrozen` | `boolean` | Whether frozen collateral prevents liquidation | | `isDelayed` | `boolean` | Whether some proceeds settle after the liquidation transaction | The payment token is specific to the selected liquidation path. If `details.approve.token` is `DefaultRWAUnderlying`, the SDK builds the liquidation call but does not obtain that token for the liquidator. First [obtain the RWA underlying](https://docs.gearbox.finance/developers/obtain-rwa-underlying) by depositing its configured ERC-20 asset. Some dedicated RWA liquidation paths accept the configured ERC-20 asset and wrap it during execution. In that case, `details.approve.token` already reports that asset. Always use the token, spender, and amount returned in `details.approve` for the selected path. Use `receivedAssets` to confirm that the liquidator supports the complete outcome, rather than relying only on the main-asset discovery filter. When an item has `isDelayed: true`, `redeemerAddress` identifies the contract holding that redemption request. Executing the liquidation assigns the redeemer—and the future claim it represents—to the liquidator. See [Preview before liquidation](https://docs.gearbox.finance/developers/delayed-redemptions#preview-before-liquidation) for the delayed-output workflow. ## 3. Obtain the execution payload Build immediately before execution so that the SDK uses current prices and selects the correct liquidation contract. This call recomputes the liquidation data independently; it does not consume the `details` object: ```typescript const transaction = await sdk.liquidations.buildLiquidationTx({ creditAccount, liquidator, }); ``` When `details.approve` is present, approve its `token` for its `spender` and `amount`. Use `details.approve.spender` as the approval target. `transaction` contains the unsigned liquidation call. Pass the approval requirement and transaction to the operator's existing transaction pipeline, which handles allowance state, simulation, gas policy, signing, submission, and monitoring. ## Integration boundary This page provides Gearbox discovery, outcome inspection, approval requirements, and unsigned liquidation calldata. The operator's existing infrastructure owns execution and service operation. ## Sources - [Gearbox SDK](https://github.com/Gearbox-protocol/sdk) - [Standard liquidation construction](https://github.com/Gearbox-protocol/periphery-v3/blob/af447ac4619ad7943d5aa7d6914dbce34a7b243e/contracts/compressors/LiquidationCompressor.sol#L100-L180) - [Delayed-redemption liquidation construction](https://github.com/Gearbox-protocol/periphery-v3/blob/af447ac4619ad7943d5aa7d6914dbce34a7b243e/contracts/compressors/subcompressors/liquidation/SecuritizeLiquidationSubcompressor.sol) - [`CreditFacadeV3.liquidateCreditAccount`](https://github.com/Gearbox-protocol/core-v3/blob/510fc6541c3767ce825929b4c311826fe81d6fa5/contracts/credit/CreditFacadeV3.sol#L280-L370) ## Delayed Redemptions Liquidation Source: https://docs.gearbox.finance/developers/delayed-redemptions File: content/developers/delayed-redemptions.mdx A delayed redemption is collateral that has been submitted to an issuer but has not yet settled into the output token. Full liquidation can transfer this pending position to the liquidator together with the account's immediate assets. ## What a redeemer is A redeemer is a contract created for one redemption request. It records the request and receives the output tokens when the issuer settles. A gateway records which account owns the redeemer and is the only contract allowed to move funds from it. During liquidation, ownership of an unclaimed redeemer moves from the Credit Account to the liquidator. The liquidator therefore receives a future claim, not immediately spendable tokens. Once settlement arrives, the liquidator claims the output through the gateway. ## Preview before liquidation The `details` object returned by [`getLiquidationDetails()`](https://docs.gearbox.finance/developers/full-liquidation#2-inspect-one-candidate) contains every output expected from the liquidation. Select the delayed ones: ```typescript const delayedOutputs = details.receivedAssets.filter( asset => asset.isDelayed, ); ``` | Value | Type | Meaning | |---|---|---| | `details.receivedAssets` | `ReceivedAsset[]` | Complete list of immediate and delayed liquidation outputs | | `delayedOutputs` | `DelayedReceivedAsset[]` | Items from `receivedAssets` whose `isDelayed` field is `true` | | `delayedOutputs[].token` | `Address` | ERC-20 expected when the redemption settles | | `delayedOutputs[].amount` | `bigint` | Exact amount when claimable; estimate while pending | | `delayedOutputs[].redeemerAddress` | `Address \| undefined` | Redeemer currently owned by the Credit Account and assigned to the liquidator if execution succeeds | | `delayedOutputs[].claimableAt` | `bigint \| undefined` | Estimated Unix timestamp; `undefined` means claimable now | This preview answers what the liquidator is buying before execution. The redeemer address is informational at this stage: the SDK builds the correct liquidation transaction, including the ownership assignment. After execution, use the liquidator address to query the redeemers it now owns. ## List current withdrawals Using the [attached SDK instance](https://docs.gearbox.finance/developers/sdk-setup), query the delayed withdrawals currently owned by the liquidator after liquidation: ```typescript const withdrawals = await sdk.liquidations.getLiquidatorWithdrawals({ liquidator, }); ``` | Value | Type | Meaning | |---|---|---| | `liquidator` | `Address` | Wallet that received the redeemers during liquidation | | `withdrawals` | `LiquidatorWithdrawal[]` | Current pending and claimable withdrawals owned by `liquidator` | | `withdrawals[].sourceToken` | `Address` | Asset submitted for redemption | | `withdrawals[].token` | `Address` | ERC-20 receivable from settlement | | `withdrawals[].amount` | `bigint` | Exact amount when claimable; estimate while pending | | `withdrawals[].claimableAt` | `bigint \| undefined` | Estimated Unix timestamp; `undefined` means claimable now | | `withdrawals[].redeemer` | `Address \| undefined` | Redeemer owned by the liquidator | The SDK queries every supported redemption gateway and returns its pending and claimable redeemers for the liquidator address. Redeemers do not need to be saved before executing the liquidation. Fully claimed withdrawals are not returned. ## Check status with the SDK Extract the redeemer addresses returned above and query their current status: ```typescript const compressor = sdk.withdrawalCompressor; if (!compressor) throw new Error("Delayed withdrawals are not supported"); const redeemers = withdrawals.flatMap(withdrawal => withdrawal.redeemer ? [withdrawal.redeemer] : [], ); const statuses = await compressor.getWithdrawalStatus(...redeemers); ``` | Variable | Type | Meaning | |---|---|---| | `compressor` | `IWithdrawalCompressorContract` | SDK reader for delayed-withdrawal state | | `redeemers` | `Address[]` | Redeemer addresses returned in `withdrawals` | | `statuses` | `WithdrawalStatus[]` | Status corresponding to each address in `redeemers` | `statuses[i]` describes `redeemers[i]`: | Status | Meaning | |---|---| | `NULL` | The address is not a supported redeemer | | `PENDING` | The issuer has not completed settlement | | `CLAIMABLE` | Output tokens are available at the redeemer | | `CLAIMED` | No pending or claimable output remains | `claimableAt` is only an estimate. Use the current status before claiming. ## Build claim calls The high-level method above is intended for monitoring. To obtain encoded claim calls, query the same data through the withdrawal compressor: ```typescript await compressor.loadWithdrawableAssets(); const withdrawalTokens = [ ...new Set( compressor .getWithdrawableAssets() .map(asset => asset.withdrawalPhantomToken), ), ]; const current = await compressor.getExternalAccountCurrentWithdrawals( liquidator, ...withdrawalTokens, ); const claimCalls = current.claimable.flatMap( withdrawal => withdrawal.claimCalls, ); ``` | Variable | Type | Meaning | |---|---|---| | `withdrawalTokens` | `Address[]` | Supported delayed-withdrawal configurations known to the SDK | | `current` | `CurrentWithdrawals` | Pending and claimable withdrawals returned by the compressor | | `current.pending` | `PendingWithdrawal[]` | Withdrawals that have not settled | | `current.claimable` | `ClaimableWithdrawal[]` | Settled withdrawals and their encoded claim calls | | `claimCalls` | `MultiCall[]` | Calls for all outputs currently available to claim | Each item in `claimCalls` contains the protocol gateway in `target` and the encoded method in `callData`. Pass those values to the operator's existing transaction pipeline. ## Protocol-specific redeemers ### Securitize Each redemption request creates a `SecuritizeRedeemer`. The redeemer sends its DS tokens to Securitize's redemption account and stores the starting NAV and timestamp. The resulting stablecoin is later delivered to the redeemer. The SDK reports: - `PENDING` while no stablecoin is available and `pendingDsTokenAmount` is non-zero; - `CLAIMABLE` as soon as the redeemer holds stablecoin; and - `CLAIMED` after the gateway has claimed the balance and cleared the pending amount. While pending, the displayed output is a NAV-based estimate. Once claimable, the output is the redeemer's actual stablecoin balance. Its generated claim call targets the `SecuritizeRedemptionGateway` and encodes `claim([redeemer])`; the gateway transfers the complete stablecoin balance to the liquidator. Securitize requires the new redeemer owner to be a registered wallet. Check `details.isLiquidatorEligible` before liquidation; the transfer reverts if the liquidator is not eligible. Source: [SecuritizeRedeemer.sol](https://github.com/Gearbox-protocol/integrations-v3/blob/midas-rwa/contracts/integrations/securitize/SecuritizeRedeemer.sol) and [SecuritizeRedemptionGateway.sol](https://github.com/Gearbox-protocol/integrations-v3/blob/midas-rwa/contracts/integrations/securitize/SecuritizeRedemptionGateway.sol). ### Midas Each redemption request creates a `MidasRedeemer`. It submits the mToken redemption to the Midas vault, stores the returned `requestId`, and records the start time. The requested quote token is later delivered to the redeemer. The SDK reports: - `PENDING` while the Midas request status is pending; - `CLAIMABLE` when the request is no longer pending and the redeemer holds quote tokens; and - `CLAIMED` when neither a pending estimate nor claimable quote-token balance remains. While pending, the displayed output is estimated from the current mToken rate and the request's quote-token rate. Once claimable, the output is the redeemer's exact quote-token balance. Its generated claim call targets the `MidasGateway` and encodes `withdrawFromRedeemer(redeemer, claimableAmount)`. Claims are per redeemer. In permissioned Midas mode, the liquidator must have the gateway's greenlisted role. Check `details.isLiquidatorEligible` before submitting the liquidation. Source: [MidasRedeemer.sol](https://github.com/Gearbox-protocol/integrations-v3/blob/midas-rwa/contracts/integrations/midas/MidasRedeemer.sol) and [MidasGateway.sol](https://github.com/Gearbox-protocol/integrations-v3/blob/midas-rwa/contracts/integrations/midas/MidasGateway.sol). ## Related pages - [SDK Setup](https://docs.gearbox.finance/developers/sdk-setup) - [Full Liquidation](https://docs.gearbox.finance/developers/full-liquidation) ## Pool Integration Source: https://docs.gearbox.finance/developers/pool-integration File: content/developers/pool-integration.mdx Use the Gearbox SDK to resolve a pool, build unsigned deposit and withdrawal transactions, and preview the token amounts. The same flow works for every pool underlying. Before continuing, [install and attach the Gearbox SDK](https://docs.gearbox.finance/developers/sdk-setup). The examples use these inputs: | Variable | Type | Meaning | |---|---|---| | `sdk` | `OnchainSDK` | Attached Gearbox SDK instance | | `poolAddress` | `Address` | Gearbox pool to integrate | | `lender` | `Address` | Wallet supplying the underlying and owning the pool shares | | `depositAmount` | `bigint` | Underlying amount to deposit, in native token units | | `sharesToRedeem` | `bigint` | Pool-share amount to redeem, in native token units | ## Resolve the pool Resolve the market once from the configured pool address: ```typescript import { RWA_UNDERLYING_DEFAULT } from "@gearbox-protocol/sdk"; const market = sdk.marketRegister.findByPool(poolAddress); const pool = market.pool.pool; const underlying = market.underlying; const underlyingMeta = sdk.tokensMeta.mustGet(underlying); const requiresRwaUnderlying = sdk.tokensMeta.isRWAUnderlying(underlyingMeta) && underlyingMeta.contractType === RWA_UNDERLYING_DEFAULT; if (pool.isPaused) throw new Error("Pool is paused"); ``` `underlying` is the ERC-20 supplied to and returned by this pool. `pool.address` is also the pool-share token address. > **If `requiresRwaUnderlying` is `true`:** the pool accepts > `DefaultRWAUnderlying`, not the ERC-20 asset wrapped by it. Follow > [Obtaining RWA Underlying](https://docs.gearbox.finance/developers/obtain-rwa-underlying) to obtain > the token, then return to the deposit flow below. ## Deposit This step assumes the lender already holds the exact `underlying` resolved above. ### Preview deposit ```typescript const expectedShares = await pool.contract.read.previewDeposit([ depositAmount, ]); ``` `expectedShares` is the expected pool-share output for `depositAmount`. ### Generate deposit transaction ```typescript const depositTransaction = pool.depositWithReferral( depositAmount, lender, 0n, ); ``` Approve `underlying` for `pool.address` with an allowance of at least `depositAmount`. `depositTransaction` is the unsigned deposit call. ## Check how much can be withdrawn Read the ERC-4626 limits through the SDK client: ```typescript const [withdrawableUnderlying, redeemableShares] = await Promise.all([ pool.contract.read.maxWithdraw([lender]), pool.contract.read.maxRedeem([lender]), ]); ``` `withdrawableUnderlying` is the current asset-denominated limit. `redeemableShares` is the current share-denominated limit. Both account for the lender's position, available pool liquidity, withdrawal fees, and pause state. ## Withdraw The SDK withdrawal builder redeems pool shares. ### Preview withdrawal ```typescript const expectedUnderlying = await pool.contract.read.previewRedeem([ sharesToRedeem, ]); ``` `expectedUnderlying` is the expected underlying output after the withdrawal fee. ### Generate withdrawal transaction ```typescript const withdrawalTransaction = pool.redeem( sharesToRedeem, lender, lender, ); ``` No pool-share approval is required when `lender` submits this transaction. If another address submits it, `lender` must approve that address to spend the shares. `withdrawalTransaction` is the unsigned redemption call. ## Pricing Use the ERC-4626 conversion methods for the current accounting rate: ```typescript const oneTokenUnit = 10n ** BigInt(pool.decimals); const [underlyingPerShare, sharesPerUnderlying] = await Promise.all([ pool.contract.read.convertToAssets([oneTokenUnit]), pool.contract.read.convertToShares([oneTokenUnit]), ]); ``` Conversions exclude operation-specific fees. Use `previewDeposit` and `previewRedeem` when preparing an actual transaction. ## Integration boundary This page provides Gearbox address resolution, current limits, previews, exact approval targets, and unsigned calldata. The lender's existing infrastructure owns allowance state, simulation, signing, submission, and monitoring. ## Sources - [Gearbox SDK pool transaction builders](https://github.com/Gearbox-protocol/sdk/blob/next/src/sdk/market/pool/PoolV310Contract.ts#L150-L181) - [Gearbox pool ERC-4626 implementation](https://github.com/Gearbox-protocol/core-v3/blob/next/contracts/pool/PoolV3.sol) ## Securitize Admin Source: https://docs.gearbox.finance/developers/securitize-admin File: content/developers/securitize-admin.mdx The Securitize Admin is the address configured as the owner of a [`SecuritizeRWAFactory`](https://github.com/Gearbox-protocol/periphery-v3/blob/2a63cf27b458c9c3b7824086da32f9dd6ee73613/contracts/rwa/SecuritizeRWAFactory.sol). It can freeze Credit Accounts managed by that `SecuritizeRWAFactory` and reassign investor control over them. Securitize determines when to use these tools. There is no separate freezer or Credit Account transfer role. The active `SecuritizeRWAFactory.owner()` has both authorities. ## Credit Account control model Each managed position links an investor, a `SecuritizeWallet`, and a Credit Account. See [Securitize DS Token Registration](https://docs.gearbox.finance/developers/securitize-ds-token-registration) for their ownership and control relationship and how both contract addresses are registered under the investor. Admin operations update state in the `SecuritizeRWAFactory`; they do not replace the `SecuritizeWallet` or change the Credit Account's onchain owner. ## Freeze behavior The admin can freeze or unfreeze: - one Credit Account; - all Credit Accounts assigned to an investor; or - an investor's Credit Accounts under one Credit Manager. While a Credit Account is frozen: - the `SecuritizeRWAFactory` rejects the investor's Credit Account operations; and - the configured RWA underlying rejects token movements to or from that Credit Account. With the current default and on-demand RWA underlying implementations, freezing also blocks liquidation of the Credit Account. Operators must account for this effect before freezing a Credit Account. Unfreezing restores these `SecuritizeRWAFactory` and RWA-underlying execution paths. Other protocol, market, token, or registry restrictions may still prevent an operation. ## Reassigning investor control The admin can reassign: - one Credit Account; - all Credit Accounts assigned to an investor; or - an investor's Credit Accounts under one Credit Manager. After reassignment, the previous investor can no longer execute Credit Account actions through the `SecuritizeRWAFactory`. The new investor becomes the authorized caller. The Credit Account's collateral, debt, `SecuritizeWallet` address, Credit Manager, and frozen status do not change. Before reassignment, the new investor address is expected to be recognized in all required Securitize registries under the same identity as the previous investor. The `SecuritizeRWAFactory` does not verify this condition. It only rejects the zero address; passing the currently assigned investor makes no change. ## Function reference All functions below can only be called by the active `SecuritizeRWAFactory.owner()`. | Function | Scope | Effect | |---|---|---| | `setCreditAccountFrozenStatus(creditAccount, frozen)` | One known Credit Account | Sets its frozen status. | | `setAllCreditAccountsFrozenStatus(investor, frozen)` | All Credit Accounts assigned to an investor | Sets the same frozen status on each Credit Account. | | `setAllCreditAccountsFrozenStatus(creditManager, investor, frozen)` | The investor's Credit Accounts under one Credit Manager | Sets the same frozen status on matching Credit Accounts. | | `transferCreditAccount(creditAccount, newInvestor)` | One known Credit Account | Reassigns investor control to `newInvestor`. | | `transferAllCreditAccounts(investor, newInvestor)` | All Credit Accounts assigned to an investor | Reassigns all of them to `newInvestor`. | | `transferAllCreditAccounts(creditManager, investor, newInvestor)` | The investor's Credit Accounts under one Credit Manager | Reassigns matching Credit Accounts to `newInvestor`. | Bulk functions iterate over the investor's recorded Credit Accounts in one transaction. Operators should simulate bulk calls with the intended Credit Account set before submitting them. Successful changes emit `SetCreditAccountFrozenStatus` for each changed freeze state or `TransferCreditAccount` for each reassigned Credit Account. Calling a freeze function with the current status, or transferring to the currently assigned investor, makes no state change and emits no event. ## Securitize Admin address The `SecuritizeRWAFactory` constructor sets the supplied `securitizeAdmin` address as its initial owner. The current authority can be read from `owner()`. `SecuritizeRWAFactory` ownership can be moved to another Securitize address using the inherited two-step ownership-transfer process: the current owner proposes the new owner, and the new address accepts the role. ## Read methods Operators can inspect the current state before building an admin transaction: | Function | Returns | |---|---| | `isCreditAccount(creditAccount)` | Whether the Credit Account is managed by this `SecuritizeRWAFactory`. | | `isFrozen(creditAccount)` | Whether a known Credit Account is frozen. | | `getInvestor(creditAccount)` | The investor currently authorized to control a known Credit Account. | | `getCreditAccounts(investor)` | All Credit Accounts currently assigned to an investor. | | `getWallet(creditAccount)` | The `SecuritizeWallet` that owns a known Credit Account. | ## Sources - [`SecuritizeRWAFactory.sol`](https://github.com/Gearbox-protocol/periphery-v3/blob/2a63cf27b458c9c3b7824086da32f9dd6ee73613/contracts/rwa/SecuritizeRWAFactory.sol) - [`SecuritizeWallet.sol`](https://github.com/Gearbox-protocol/periphery-v3/blob/2a63cf27b458c9c3b7824086da32f9dd6ee73613/contracts/rwa/SecuritizeWallet.sol) - [`IRWAFactory.sol`](https://github.com/Gearbox-protocol/periphery-v3/blob/2a63cf27b458c9c3b7824086da32f9dd6ee73613/contracts/interfaces/base/IRWAFactory.sol) - [Default RWA Underlying](https://docs.gearbox.finance/developers/rwa-underlying) ## Default RWA Underlying Source: https://docs.gearbox.finance/developers/rwa-underlying File: content/developers/rwa-underlying.mdx [`DefaultRWAUnderlying`](https://github.com/Gearbox-protocol/periphery-v3/blob/main/contracts/rwa/DefaultRWAUnderlying.sol) is a 1:1 ERC-4626 wrapper used as the underlying token of a Gearbox RWA pool. It connects the pool to borrower-level compliance controls without applying those controls to ordinary liquidity providers. ## Purpose RWA markets may need to freeze a borrower's Credit Account while preserving normal pool operations for LPs. `DefaultRWAUnderlying` provides the token-level enforcement point for that boundary. The wrapper exists primarily to block token movements involving a frozen Credit Account, including movements used during liquidation. Other operations on a frozen Credit Account are blocked by the configured RWA factory. It does not represent the borrower's RWA collateral. LPs interact with the wrapper's configured ERC-20 asset, `DefaultRWAUnderlying`, and Gearbox pool shares. ## ERC-4626 behavior The wrapper uses the standard ERC-4626 interface: - `deposit` and `mint` wrap the configured ERC-20 asset; - `withdraw` and `redeem` return that asset; and - conversions between the asset and wrapper shares are fixed at 1:1. ```solidity uint256 wrapperShares = rwaUnderlying.previewDeposit(assetAmount); uint256 assetOut = rwaUnderlying.previewRedeem(wrapperShares); ``` The Gearbox pool has a separate exchange rate between `DefaultRWAUnderlying` and pool shares. See [Obtaining RWA Underlying](https://docs.gearbox.finance/developers/obtain-rwa-underlying) to mint or redeem the wrapper token, then use the standard [Pool Integration](https://docs.gearbox.finance/developers/pool-integration) flow. ## Freeze scope Before a wrapper-token transfer, `DefaultRWAUnderlying` checks both the sender and recipient against its configured RWA factory. The transfer reverts only if an address is both: 1. a Credit Account registered by that factory; and 2. marked as frozen by the factory. This check is applied to the transfer's `from` and `to` addresses. See [`_beforeTokenTransfer` and `_revertIfFrozenCreditAccount`](https://github.com/Gearbox-protocol/periphery-v3/blob/2a63cf27b458c9c3b7824086da32f9dd6ee73613/contracts/rwa/DefaultRWAUnderlying.sol#L62-L70) in the implementation. ## Freeze authority and storage `DefaultRWAUnderlying` does not define a freezer role and does not store frozen addresses. It stores only an immutable reference to its configured RWA factory. In the Securitize implementation, [`SecuritizeRWAFactory`](https://github.com/Gearbox-protocol/periphery-v3/blob/main/contracts/rwa/SecuritizeRWAFactory.sol) inherits `Ownable2Step`. Its constructor receives a `securitizeAdmin` address and sets that address as the initial factory owner. The active factory owner is the only address authorized to call: - `setCreditAccountFrozenStatus` for one Credit Account; - `setAllCreditAccountsFrozenStatus(investor, frozen)` for all accounts belonging to an investor; or - `setAllCreditAccountsFrozenStatus(creditManager, investor, frozen)` for an investor's accounts in one Credit Manager. Ownership can subsequently be transferred through the factory's two-step ownership process. There is no separately assigned freezer role. The state is stored in the factory's Credit Account mapping: ```solidity mapping(address creditAccount => CreditAccountInfo) internal _creditAccountInfo; struct CreditAccountInfo { address wallet; address investor; bool frozen; } ``` The relevant storage and authority boundary is: | Item | Contract | Location | |---|---|---| | Active freeze authority | `SecuritizeRWAFactory` | inherited `owner()` state | | Frozen status | `SecuritizeRWAFactory` | `_creditAccountInfo[creditAccount].frozen` | | Factory used for checks | `DefaultRWAUnderlying` | immutable `_FACTORY` reference | When wrapper tokens move, `DefaultRWAUnderlying` calls `isCreditAccount(account)` and `isFrozen(account)` on that factory. It does not copy the frozen status into its own storage. ## LPs do not require KYC An ordinary LP address and the Gearbox pool are not registered borrower Credit Accounts. Consequently, the additional logic in `DefaultRWAUnderlying`: - does not create an LP allowlist; - does not require LP identity registration or KYC; and - does not provide a mechanism for marking an arbitrary LP address as frozen. LPs use the standard ERC-4626 deposit and redemption methods. Borrower compliance is handled separately at the Credit Account level. This boundary applies to the additional freeze logic in `DefaultRWAUnderlying`. It does not remove controls or risks that exist outside the wrapper, such as issuer-level controls in the configured ERC-20 asset, a paused Gearbox pool, or insufficient pool liquidity for an immediate withdrawal. ## Contract relationships An integration can verify the wrapper and pool relationship onchain: ```solidity require(rwaUnderlying.asset() == expectedAssetAddress, "Unexpected wrapper asset"); require(rwaUnderlying.getFactory() == rwaFactoryAddress, "Unexpected RWA factory"); require(pool.asset() == address(rwaUnderlying), "Unexpected pool underlying"); ``` The factory controls borrower Credit Account registration and frozen status. The wrapper only reads that state when enforcing transfers; it does not maintain a separate freeze list. ## See also - [Obtaining RWA Underlying](https://docs.gearbox.finance/developers/obtain-rwa-underlying) - [Pool Integration](https://docs.gearbox.finance/developers/pool-integration) - [`DefaultRWAUnderlying.sol`](https://github.com/Gearbox-protocol/periphery-v3/blob/main/contracts/rwa/DefaultRWAUnderlying.sol) - [`IRWAUnderlying.sol`](https://github.com/Gearbox-protocol/periphery-v3/blob/main/contracts/interfaces/base/IRWAUnderlying.sol) - [`IRWAFactory.sol`](https://github.com/Gearbox-protocol/periphery-v3/blob/main/contracts/interfaces/base/IRWAFactory.sol) ## Securitize DS Token Registration Source: https://docs.gearbox.finance/developers/securitize-ds-token-registration File: content/developers/securitize-ds-token-registration.mdx The [`SecuritizeRWAFactory`](https://github.com/Gearbox-protocol/periphery-v3/blob/2a63cf27b458c9c3b7824086da32f9dd6ee73613/contracts/rwa/SecuritizeRWAFactory.sol) is the authorization registry for Securitize-enabled Credit Accounts. It records who may operate each Credit Account and the [`SecuritizeWallet`](https://github.com/Gearbox-protocol/periphery-v3/blob/2a63cf27b458c9c3b7824086da32f9dd6ee73613/contracts/rwa/SecuritizeWallet.sol) through which calls are executed. The integration uses three different addresses for one investor position: | Address | What it is | |---|---| | Investor | The external address recognized by Securitize. It signs registration authorizations and submits actions to the `SecuritizeRWAFactory`. | | `SecuritizeWallet` | A contract deployed for one position. Gearbox records it as the Credit Account's owner, or borrower. | | [`CreditAccount`](https://github.com/Gearbox-protocol/core-v3/blob/510fc6541c3767ce825929b4c311826fe81d6fa5/contracts/credit/CreditAccountV3.sol) | A separate Gearbox contract that holds the position's collateral and debt. | ## SecuritizeRWAFactory — authorization registry For each Credit Account, the `SecuritizeRWAFactory` records its `SecuritizeWallet`, authorized investor, and frozen status. Before forwarding a multicall, it checks that the caller is that investor and the Credit Account is not frozen. This is operational authorization, not Gearbox ownership. The Credit Manager records the `SecuritizeWallet` as the Credit Account's borrower. Freezing Credit Accounts and reassigning investor control are covered separately in [Securitize Admin](https://docs.gearbox.finance/developers/securitize-admin). ### When DS token eligibility is checked DS token eligibility is checked when the contracts are registered for a specific DS token. The [`SecuritizeDegenNFT`](https://github.com/Gearbox-protocol/periphery-v3/blob/2a63cf27b458c9c3b7824086da32f9dd6ee73613/contracts/rwa/SecuritizeDegenNFT.sol) first checks through that token's [`VaultRegistrar`](https://github.com/Gearbox-protocol/periphery-v3/blob/2a63cf27b458c9c3b7824086da32f9dd6ee73613/contracts/interfaces/external/securitize/IVaultRegistrar.sol) that the investor is registered. Because the `SecuritizeDegenNFT` has the registrar's operator role, it can then register the `CreditAccount` and `SecuritizeWallet` contract addresses as vaults belonging to that investor. ## Changes to investor eligibility Gearbox does not automatically remove DS token registrations, freeze `CreditAccount` contracts, or reassign them when an investor's Securitize eligibility changes. The `SecuritizeRWAFactory` continues to recognize the recorded investor until a Securitize operator freezes or reassigns the `CreditAccount`. The DS token continues to apply its current registry rules to transfers. ## Sources - [`SecuritizeRWAFactory.sol`](https://github.com/Gearbox-protocol/periphery-v3/blob/2a63cf27b458c9c3b7824086da32f9dd6ee73613/contracts/rwa/SecuritizeRWAFactory.sol) - [`SecuritizeDegenNFT.sol`](https://github.com/Gearbox-protocol/periphery-v3/blob/2a63cf27b458c9c3b7824086da32f9dd6ee73613/contracts/rwa/SecuritizeDegenNFT.sol) - [`SecuritizeWallet.sol`](https://github.com/Gearbox-protocol/periphery-v3/blob/2a63cf27b458c9c3b7824086da32f9dd6ee73613/contracts/rwa/SecuritizeWallet.sol) - [`IVaultRegistrar.sol`](https://github.com/Gearbox-protocol/periphery-v3/blob/2a63cf27b458c9c3b7824086da32f9dd6ee73613/contracts/interfaces/external/securitize/IVaultRegistrar.sol) ## Obtaining RWA Underlying Source: https://docs.gearbox.finance/developers/obtain-rwa-underlying File: content/developers/obtain-rwa-underlying.mdx Some Gearbox RWA pools use [`DefaultRWAUnderlying`](https://docs.gearbox.finance/developers/rwa-underlying) as their underlying. Obtain it by depositing the wrapper's configured ERC-20 asset. This does not require KYC or an allowlist step. After obtaining the token, use the standard [Pool Integration](https://docs.gearbox.finance/developers/pool-integration) flow without changing the pool logic. Before continuing, [install and attach the Gearbox SDK](https://docs.gearbox.finance/developers/sdk-setup). The examples use these inputs: | Variable | Type | Meaning | |---|---|---| | `sdk` | `OnchainSDK` | Attached Gearbox SDK instance | | `poolAddress` | `Address` | RWA pool whose underlying must be obtained | | `lender` | `Address` | Wallet supplying the configured asset and receiving the RWA underlying | | `assetAmount` | `bigint` | ERC-20 asset amount to deposit, in native token units | | `rwaUnderlyingAmount` | `bigint` | RWA underlying amount to redeem, in native token units | ## Resolve the wrapper Resolve the RWA underlying and its ERC-20 asset from the pool: ```typescript import { BaseContract, RWA_UNDERLYING_DEFAULT, } from "@gearbox-protocol/sdk"; import { iRWAUnderlyingAbi } from "@gearbox-protocol/sdk/abi/rwa/iRWAUnderlying"; const market = sdk.marketRegister.findByPool(poolAddress); const meta = sdk.tokensMeta.mustGet(market.underlying); if ( !sdk.tokensMeta.isRWAUnderlying(meta) || meta.contractType !== RWA_UNDERLYING_DEFAULT ) { throw new Error("Pool does not use DefaultRWAUnderlying"); } const underlyingAsset = meta.asset; const rwaUnderlying = new BaseContract(sdk, { addr: market.underlying, abi: iRWAUnderlyingAbi, name: "DefaultRWAUnderlying", }); ``` `underlyingAsset` is the token supplied to and returned by the wrapper. `rwaUnderlying.address` is the token used by the Gearbox pool. ## Obtain RWA underlying ### Preview deposit ```typescript const expectedRwaUnderlying = await rwaUnderlying.contract.read.previewDeposit([assetAmount]); ``` The wrapper converts its configured asset 1:1, but use the preview rather than hardcoding that result. ### Generate deposit transaction ```typescript const depositTransaction = rwaUnderlying.createRawTx({ functionName: "deposit", args: [assetAmount, lender], }); ``` Approve `underlyingAsset` for `rwaUnderlying.address` with an allowance of at least `assetAmount`. `depositTransaction` is the unsigned wrapper deposit call. After execution, approve the received RWA underlying to the Gearbox pool and continue with [Pool Integration](https://docs.gearbox.finance/developers/pool-integration#deposit). ## Check how much can be redeemed ```typescript const [withdrawableAsset, redeemableRwaUnderlying] = await Promise.all([ rwaUnderlying.contract.read.maxWithdraw([lender]), rwaUnderlying.contract.read.maxRedeem([lender]), ]); ``` `withdrawableAsset` is the asset-denominated limit. `redeemableRwaUnderlying` is the share-denominated limit. ## Redeem to the underlying asset ### Preview redemption ```typescript const expectedAsset = await rwaUnderlying.contract.read.previewRedeem([ rwaUnderlyingAmount, ]); ``` ### Generate redemption transaction ```typescript const redeemTransaction = rwaUnderlying.createRawTx({ functionName: "redeem", args: [rwaUnderlyingAmount, lender, lender], }); ``` No approval is required when `lender` submits the redemption. If another address submits it, `lender` must approve that address to spend the RWA underlying. `redeemTransaction` is the unsigned wrapper redemption call. ## Pricing ```typescript const [rwaUnderlyingOut, assetOut] = await Promise.all([ rwaUnderlying.contract.read.convertToShares([assetAmount]), rwaUnderlying.contract.read.convertToAssets([rwaUnderlyingAmount]), ]); ``` `DefaultRWAUnderlying` currently defines a 1:1 conversion in both directions. Use `previewDeposit` and `previewRedeem` when preparing an actual transaction. ## Integration boundary This page provides Gearbox address resolution, limits, previews, approval targets, and unsigned calldata. The lender's existing infrastructure owns allowance state, simulation, signing, submission, and monitoring. For why this token exists, how freeze authority works, and why it does not add direct freeze risk to LP wallets, see [Default RWA Underlying](https://docs.gearbox.finance/developers/rwa-underlying). ## Sources - [`DefaultRWAUnderlying`](https://github.com/Gearbox-protocol/periphery-v3/blob/main/contracts/rwa/DefaultRWAUnderlying.sol) - [Gearbox SDK RWA underlying ABI](https://github.com/Gearbox-protocol/sdk/blob/next/src/abi/rwa/iRWAUnderlying.ts) ## Deployment Addresses Source: https://docs.gearbox.finance/developers/deployments File: content/developers/deployments.mdx Gearbox v3.1 contracts are deployed through a [deterministic deployer](https://ethglobal.com/showcase/deterministic-deployer-p3eyi), so every system contract has the same address on all supported chains. This page is the canonical address list for the protocol. ## Programmatic Discovery The recommended way to resolve contract addresses at runtime is through the **AddressProvider** contract. Rather than hardcoding addresses, query the AddressProvider to get the latest verified deployment for any protocol component: ```typescript import { GearboxSDK } from '@gearbox-protocol/sdk'; const sdk = await GearboxSDK.attach({ client, marketConfigurators: [] }); // Resolve any protocol contract by its key const [address, version] = sdk.addressProvider.mustGetLatest( AP_MARKET_COMPRESSOR, VERSION_RANGE_310 ); ``` See the [SDK setup guide](https://docs.gearbox.finance/developers/gm-start-ts) for full initialization details. *** ## System Contracts | Contract | Address | | ------------------------ | -------------------------------------------- | | Address Provider | `0xF7f0a609BfAb9a0A98786951ef10e5FE26cC1E38` | | Bytecode Repository | `0x1cE2B1BE96a082b1b1539F80d5D8f82Ec06a0f9A` | | Cross-Chain Governance | `0xcCCCCcCc42B7DA9fdEc1761698Fb55fdD41CDF55` | | Instance Manager | `0x77777777144339Bdc3aCceE992D8d4D31734CB2e` | | Instance Manager Proxy | `0xBcD875f0D62B9AA22481c81975F9AE1753Fc559A` | | Bot List | `0x0Bc03983Da93021a374C964A22b73865220Ce962` | | Price Feed Store | `0x74A868AC479EE145029bB80827BB77F7B7c441cB` | | GEAR Staking | `0x2fcbD02d5B1D52FC78d4c02890D7f4f47a459c33` | *** ## Factories Used by market configurators to deploy and upgrade market components. | Contract | Address | | --------------------------- | -------------------------------------------- | | Market Configurator Factory | `0x7D60CfaF7c2cec210638A5e46E4000894830C034` | | Pool Factory | `0x2238eDf33a72860cDbaec5F83ec246Df9e85c8E2` | | Credit Factory | `0x81Cda0aB38d8Bd0732123Eb0e36C0C566d35DADD` | | Price Oracle Factory | `0xF7533CDCE5A2F7BF78B6fbf4B05f04F45D10140B` | | Interest Rate Model Factory | `0xA7dE2e941c8818E51D1Fd84111d8F71dcafa6C3B` | | Rate Keeper Factory | `0xBEde127c14407B9c345F5D7fAE5782ab8eAa33f3` | | Loss Policy Factory | `0x0E535b7D073a93646512cEa18fa7e650CC2b17C4` | *** ## Periphery Contracts Read-only compressors and the router, registered in the AddressProvider under `GLOBAL::*` keys. | Contract | Address | | ----------------------- | -------------------------------------------- | | Market Compressor | `0x70F1753a765C4df582FFA3B8d96AB492714E8992` | | Account Compressor | `0x4115708Fc8fe6bB392De2e0C21c2C81dA2222394` | | Credit Suite Compressor | `0x93Cba8445b13a05287bFf90D882cbcB514D617b7` | | Price Feeds Compressor | `0x847a05C22c7508C674342A95356Adf9b3a0e0D57` | | Gauge Compressor | `0x12c8faEdD62cF0C5d4D742E57B98737a9a3F5E0f` | | Periphery Compressor | `0xa7ED6dB5761613CaE7CaCfAAE9Dca07a77809F9d` | | Rewards Compressor | `0x19Ca61E672d1c6105f609418bfDC784F92F4Ecf0` | | Token Compressor | `0xAe3Dd11e5a7f99eD4cba2768D4095a55fbF7841B` | | Router | `0x00aDE38841AB8c6e236E232041e43B41d74B8B45` | *** ## Activated Chains Chains activated through cross-chain governance, with the per-chain treasury, wrapped native token, and GEAR token addresses. This table is generated from the `InstanceManager.activate` calls executed by the Cross-Chain Governance multisig on Ethereum (`npm run generate:addresses`). | Chain | Chain ID | Treasury | WETH | GEAR | | ----- | -------- | -------- | ---- | ---- | | Ethereum | 1 | `0x3e965117a51186e41c2bb58b729a1e518a715e5f` | `0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2` | `0xba3335588d9403515223f109edc4eb7269a9ab5d` | | Optimism | 10 | `0x1acc5bc353f23b901801f3ba48e1e51a14263808` | `0x4200000000000000000000000000000000000006` | `0x39e6c2e1757ae4354087266e2c3ea9ac4257c1eb` | | BNB Chain | 56 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c` | not deployed | | Unichain | 130 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x4200000000000000000000000000000000000006` | not deployed | | Polygon | 137 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x0d500b1d8e8ef31e21c99d1db9a6444d3adf1270` | not deployed | | Monad | 143 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x3bd359c1119da7da1d913d1c4d2b7c461115433a` | not deployed | | Sonic | 146 | `0x74028cf1cba6a4513c9a27137e7d0f3847833795` | `0x039e2fb66102314ce7b64ce5ce3e5183bc94ad38` | `0x0fdbce271bea0d9819034cd09021e0bbe94be3fd` | | X Layer | 196 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0xe538905cf8410324e03a5a23c1c177a474d59b2b` | not deployed | | B2 Network | 223 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x4200000000000000000000000000000000000006` | not deployed | | Fraxtal | 252 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0xfc00000000000000000000000000000000000002` | not deployed | | World Chain | 480 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x4200000000000000000000000000000000000006` | not deployed | | Chain 777 | 777 | `0x96992b7e28147767701d4408fc45eaba86c30f15` | `0x76818770d192a506f90e79d5cb844e708be0d7a0` | not deployed | | HyperEVM | 999 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x5555555555555555555555555555555555555555` | not deployed | | Polygon zkEVM | 1101 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x4f9a0e7fd2bf6067db6994cf12e4495df938e6e9` | not deployed | | Lisk | 1135 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x4200000000000000000000000000000000000006` | not deployed | | Soneium | 1868 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x4200000000000000000000000000000000000006` | not deployed | | Swellchain | 1923 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x4200000000000000000000000000000000000006` | not deployed | | Morph | 2818 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x5300000000000000000000000000000000000011` | not deployed | | Botanix | 3637 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x0d2437f93fed6ea64ef01ccde385fb1263910c56` | not deployed | | MegaETH | 4326 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x4200000000000000000000000000000000000006` | not deployed | | Beam | 4337 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0xd51bfa777609213a653a2cd067c9a0132a2d316a` | not deployed | | Mantle | 5000 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x78c1b0c915c4faa5fffa6cabf0219da63d7f4cb8` | not deployed | | Somnia | 5031 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x046ede9564a72571df6f5e44d0405360c0f4dcab` | not deployed | | Superseed | 5330 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x4200000000000000000000000000000000000006` | not deployed | | Chain 5920 | 5920 | `0x18b1778f45944d1ce779a5bf2a386215d8f04d5f` | `0x32e10f12e5de1f8f591c83bbcb920e39a8f172f4` | not deployed | | MegaETH Testnet | 6342 | `0x18b1778f45944d1ce779a5bf2a386215d8f04d5f` | `0x776401b9bc8aae31a685731b7147d4445fd9fb19` | not deployed | | Nibiru | 6900 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x0cacf669f8446beca826913a3c6b96acd4b02a97` | not deployed | | Kaia | 8217 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x19aac5f612f524b754ca7e7c41cbfa2e981a4432` | not deployed | | Base | 8453 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x4200000000000000000000000000000000000006` | not deployed | | Plasma | 9745 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x6100e367285b01f48d07953803a2d8dca5d19873` | not deployed | | Monad Testnet | 10143 | `0x18b1778f45944d1ce779a5bf2a386215d8f04d5f` | `0x760afe86e5de5fa0ee542fc7b7b713e1c5425701` | not deployed | | Mode | 34443 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x4200000000000000000000000000000000000006` | not deployed | | Arbitrum | 42161 | `0x2c31effe426765e68a43163a96dd13df70b53c14` | `0x82af49447d8a07e3bd95bd0d56f35241523fbab1` | `0x2f26337576127efabeec1f62be79db1bca9148a4` | | Celo | 42220 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x471ece3750da237f93b8e339c536989b8978a438` | not deployed | | Etherlink | 42793 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0xc9b53ab2679f573e480d01e0f49e2b5cfb7a3eab` | not deployed | | Hemi | 43111 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x4200000000000000000000000000000000000006` | not deployed | | Avalanche | 43114 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0xb31f66aa3c1e785363f0875a1b74e27b85fd66c7` | not deployed | | Sophon | 50104 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x2b1a859de6a55c553520d7780bc5805712b128f9` | not deployed | | Ink | 57073 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x4200000000000000000000000000000000000006` | not deployed | | Linea | 59144 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0xe5d7c2a44ffddf6b295a15c148167daaaf5cf34f` | not deployed | | BOB | 60808 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x4200000000000000000000000000000000000006` | not deployed | | Berachain | 80094 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0x6969696969696969696969696969696969696969` | not deployed | | Plume | 98866 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0xea237441c92cae6fc17caaf9a7acb3f953be4bd1` | not deployed | | Taiko | 167000 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0xa51894664a773981c6c112c43ce576f315d5b1b6` | not deployed | | Bitlayer | 200901 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0xff204e2681a6fa0e2c3fade68a1b28fb90e4fc5f` | not deployed | | Katana | 747474 | `0xef78f5ffd8c6c5aa45bcab7f4ba638b0a4fbc7a1` | `0xee7d8bcfb72bc1880d0cf19822eb0a2e6577ab62` | not deployed | | Chain 5042002 | 5042002 | `0x6763fe48cc800f24c128ce651257c9f991081d1a` | `0x3600000000000000000000000000000000000000` | not deployed | | RISE Testnet | 11155931 | `0x18b1778f45944d1ce779a5bf2a386215d8f04d5f` | `0x4200000000000000000000000000000000000006` | not deployed | *** ## Notes - Always prefer the **AddressProvider** for programmatic address resolution. Hardcoded addresses may become stale after protocol upgrades. - Market-specific contracts (Pools, Credit Managers, Credit Facades) are discoverable through the Market Compressor once you have the AddressProvider. - For a complete list of address keys, see the `AP_*` constants exported by the SDK. ## Security & Audits Source: https://docs.gearbox.finance/developers/security File: content/developers/security.mdx Gearbox Protocol takes security seriously. The protocol has undergone multiple independent audits and maintains an active bug bounty program. ## Audit Reports Gearbox smart contracts have been audited by leading security firms. The following reports cover the core protocol and its extensions: | Auditor | Scope | Report | | --------------- | ------------------ | ------------------------------------------------------- | | ChainSecurity | Core V3 | [View Report](https://github.com/Gearbox-protocol/security/blob/main/audits/PLACEHOLDER) | | Consensys Diligence | Core V3 | [View Report](https://github.com/Gearbox-protocol/security/blob/main/audits/PLACEHOLDER) | | Sigma Prime | V3 Integrations | [View Report](https://github.com/Gearbox-protocol/security/blob/main/audits/PLACEHOLDER) | | ABDK | V3 Math Libraries | [View Report](https://github.com/Gearbox-protocol/security/blob/main/audits/PLACEHOLDER) | > Links above are placeholders. Visit the [Gearbox security repository](https://github.com/Gearbox-protocol/security) for the latest audit reports. *** ## Bug Bounty Program Gearbox maintains an active bug bounty program on **Immunefi**, one of the largest Web3 security platforms. - **Platform:** [Immunefi](https://immunefi.com/) - **Scope:** Smart contracts, protocol logic, and integrations - **Rewards:** Up to $1,000,000 for critical vulnerabilities (severity-dependent) If you discover a potential vulnerability, please report it through the Immunefi platform rather than public disclosure. Responsible disclosure is critical for protecting user funds. *** ## Bytecode Repository (BCR) Verification Gearbox uses a Bytecode Repository (BCR) to ensure that only audited, verified bytecode is deployed on-chain. This provides an additional layer of security beyond source-code audits by verifying the exact compiled output. For details on how BCR verification works and how to check deployed contracts, see [BCR Verification](https://docs.gearbox.finance/developers/gp-bcr). *** ## Security Contact For security-related inquiries that do not fall under the bug bounty program: - **Email:** security@gearbox.fi - **PGP Key:** Available on the [Gearbox security repository](https://github.com/Gearbox-protocol/security) Please do not report vulnerabilities via email. Use the Immunefi bug bounty program for all vulnerability disclosures. *** ## Security Practices The Gearbox Protocol follows several security best practices: - **Multiple independent audits** before each major release - **Formal verification** of critical mathematical components - **Timelocks and multisig governance** for parameter changes - **Immutable core logic** with upgradeable configuration - **On-chain BCR verification** ensuring only audited bytecode is deployed - **Continuous monitoring** of protocol health and anomalous activity ## Glossary Source: https://docs.gearbox.finance/developers/glossary File: content/developers/glossary.mdx Key terms used throughout the Gearbox Protocol documentation. | Term | Definition | | --- | --- | | Adapter | A thin wrapper contract that translates Credit Account multicalls into calls to an external DeFi protocol (e.g., Uniswap, Aave), enforcing collateral checks before and after execution. | | Bytecode Repository (BCR) | An on-chain registry of audited contract bytecode. Deployments are verified against the BCR to ensure only approved, audited code runs in production. | | Credit Account | An isolated smart-contract account that holds a user's collateral and borrowed funds. All leveraged operations happen inside a Credit Account. | | Credit Configurator | The admin-facing contract that governs a Credit Manager's parameters, such as allowed tokens, adapters, debt limits, and liquidation thresholds. | | Credit Facade | The user-facing entry point for a Credit Manager. It validates multicalls, enforces health-factor checks, and emits events for account operations. | | Credit Manager | The core contract that manages Credit Accounts for a given market. It tracks collateral, debt, and permissions, and delegates user interactions to the Credit Facade. | | Credit Suite | The combination of a Credit Manager, its Credit Facade, and its Credit Configurator, together forming the complete management layer for leveraged accounts in a market. | | Cross-Chain Multisig (CCM) | A governance mechanism that coordinates administrative actions across multiple chains, ensuring consistent parameter changes for Gearbox deployments on different networks. | | Debt Ceiling | The maximum total amount that can be borrowed from a pool by all Credit Managers combined, limiting the pool's overall leverage exposure. | | Diesel Token | The ERC-20 LP share token received when depositing into a Gearbox pool. Its value appreciates over time as interest accrues to the pool. | | Health Factor | The ratio of a Credit Account's total weighted collateral value to its total debt. A health factor below 1.0 means the account is eligible for liquidation. | | Instance | A single deployment of the Gearbox Protocol on a specific chain, consisting of an AddressProvider and all contracts registered through it. | | Instance Owner | The governance address (typically a multisig or DAO) that controls an Instance's AddressProvider and can register or update protocol contracts. | | Liquidation Threshold (LT) | A per-token coefficient (in basis points) that discounts a collateral token's value when computing the weighted collateral for health-factor calculations. A lower LT means the protocol treats the token more conservatively. | | Market Curator | An entity or role responsible for configuring and managing a specific market's parameters, including allowed collaterals, debt limits, and risk settings. | | Multicall | A batched sequence of operations executed atomically on a Credit Account within a single transaction. All health-factor checks are deferred until the end of the batch. | | Omni-EVM | Gearbox's cross-chain execution model that allows Credit Accounts to interact with protocols on multiple EVM-compatible chains from a single position. | | Pool | A lending pool that accepts deposits from liquidity providers and lends to Credit Managers. Each pool is denominated in a single underlying token. | | Protocol DAO | The decentralized governance body that oversees the Gearbox Protocol, controlling upgrades, risk parameters, and treasury operations. | | Quota | A per-token borrowing allocation within a pool that limits how much of a specific collateral type can be used across all Credit Accounts. | | Quota Rate | The additional interest rate (RAY-scaled, per-second) charged on a Credit Account for holding a non-underlying collateral token that requires a quota. | | Total Weighted Value (TWV) | The sum of each collateral token's balance multiplied by its price and its liquidation threshold. TWV divided by total debt gives the health factor. | # Curator documentation Market-curator operations, configuration, governance execution, price feeds, adapter setup, and market activation. ## The Market Source: https://docs.gearbox.finance/curators/the-market File: content/curators/the-market.mdx ## Market Structure ### Market components Gearbox uses a hierarchical, tree-structured constraint model: Pools define global rules, Credit Managers inherit and specialize them, and Credit Accounts inherit both. Every node operates strictly within the envelopes defined by its ancestors, ensuring consistent risk and parameter discipline across all strategies. 1. **Pool (Global Constraint Layer):** Defines system-wide parameters: eligible collateral types, price sources, utilization curve, and global limits. All downstream components inherit these constraints. 2. **Credit Managers (Strategy Constraint Layer):** Each Credit Manager refines the global constraints into strategy-specific ones: position-level rules, leverage parameters, liquidation settings and more. Credit Manager configuration + Pool-level boundaries are applied to all the credit accounts. 3. **Credit Accounts (Execution Layer):** Individual accounts execute under both the global Pool constraints and the strategy-level constraints of their Credit Manager. ![Figure](https://docs.gearbox.finance/assets/docs/curators/the-market/01-market-structure.png) ### How Market Rules Shape Outcomes Understanding the rules at each level guides decision-making process for every participant: * **For lending users (LPs and borrowers)** * Constraints set the credit risk and expected yield for LPs. Tighter settings reduce risk and also reduce return. * Borrowers must operate within market parameters, so they should review the rules before taking leverage. * **For curators** * Constraints determine the target investors by fixing the risk and return profile on both supply and borrow sides. * **For asset issuers and applications** * Market configuration includes parameters that shape UX: external integrations, capital capacity, and liquidation discounts influence how end users experience the product. ### Market-specific rules #### Pool-level rules If a user disagrees with these terms, they need to select another pool. * **Total debt limit:** maximum that can be borrowed across the entire pool * **Collateral limit:** maximum that can be borrowed against each token * **Main Price Feed:** price source for calculating account value and triggering liquidations * **Reserve Price Feed:** runs safety checks on operations and can block Credit Account actions to protect LPs * **Increase Rate:** one-time fee whenever exposure to a collateral increases * **Collateral-specific rate:** extra interest for borrowing against a given collateral * **IRM:** utilization-based interest rate model * **Loss Policy:** additional liquidation logic for cases that create bad debt **Credit Manager-level rules** If a user disagrees with these terms, they can choose another Credit Manager within the same pool. * **Total debt limit:** maximum aggregate debt of all Credit Accounts created from this Credit Manager * **MinDebt:** minimum required debt for a Credit Account * **MaxDebt:** maximum permitted debt for a Credit Account * **Liquidation Premium:** portion of collateral value paid to the liquidator during liquidation * **Liquidation Fee:** portion of collateral value paid to the curator and Gearbox DAO during liquidation * **Max Enabled Tokens:** number of different collateral tokens that can count toward account value * **Interest Fee:** extra rate on top of the IRM and collateral-specific rate, split between the curator and DAO * **List of allowed collaterals and their LT** (loan to value) * **List of allowed adapters:** restricts which external contracts a Credit Account can use * **Expiration Policy:** curator may set an expiration; after the cutoff date, all Credit Accounts become liquidatable regardless of Health Factor with penalties set by the expired liquidation fee and premium parameters. ## Fee sharing Source: https://docs.gearbox.finance/curators/fee-sharing File: content/curators/fee-sharing.mdx ## Fee sharing ### What fees does Gearbox take? * Interest Fee\ Fee taken from the total interest paid by borrower. Paid when user repays debt * Liquidation Fee\ Fee taken from liquidated collateral *** ### Who set the fees value? Both Interest Fee and Liquidation fee is controlled only by a Curator. *** ### Accrued fees as insurance buffer Both Curator and DAO fees are accumulated on Treasury Splitter contract which is unique for every curator. Curator and DAO have to claim accrued fees from the contract. If a liquidation happens with bad debt, fees from Treasury Splitter contract are burnt to cover loss, so unclaimed fees act as an insurance buffer. *** ### How is the fee split between Curator and Gearbox DAO? All the fees taken by the protocol are split 50/50 between DAO and Curator by default. To change this proportion both Gearbox DAO and Curator should sign transactions on TreasurySplitter contract (requires DAO proposal). *** ### Practical considerations Both Interest and Liquidation fees are set on Credit Manager level. Some examples when it can be useful: * Charge 0% fee on first 5,000,000 USDC borrowed: * Create Credit Manager with limit of 5,000,000 and set its fee to 0% * Once the limit is reached set it to 0. It will allow existing CM users to stay at 0% while disallowing new positions to be opened * Create a new Credit Manager with nonzero Interest Fee keeping other parameters untouched. That will result in new users opening positions with nonzero fee. * Charge higher fee for borrowing at exclusive terms: * Create Credit Manager specifically for collaterals with boosts negotiated by curator * Projects issuing the collateral may have private lp deals or offer higher rewards for position opened for specified period of time. Curator may charge additional fee for bringing the opportunity to borrowers ![Figure](https://docs.gearbox.finance/assets/docs/curators/fee-sharing/01-fees.png) ## Deployment addresses Source: https://docs.gearbox.finance/curators/deployment-addresses File: content/curators/deployment-addresses.mdx ## Deployment addresses The canonical list of protocol deployment addresses lives in the developers section: [Deployment Addresses](https://docs.gearbox.finance/developers/deployments). All system contracts are deployed through a deterministic deployer and share the same address on every supported chain. For runtime address resolution, query the AddressProvider as described on that page. ## Create a Market Source: https://docs.gearbox.finance/curators/create-a-market File: content/curators/create-a-market.mdx ## Prerequisites: The Price Feed Check Before creating a market, the underlying asset (the token you want lenders to deposit) must be whitelisted in the **Price Feed Store** of the current chain. **Check Availability:** 1. Go to the **Price Feed Store** section in the interface (click on the needed chain on [Instances page](https://permissionless.gearbox.foundation/instances)) 2. Search for your target token (e.g., USDC, WETH). 3. **If it exists:** Proceed to the steps below. 4. **If it is missing:** You must add it first. Guide: [add-required-price-feeds](https://docs.gearbox.finance/curators/add-required-price-feeds) ## Configuration Walkthrough []() ## Market Parameters 1 ### Asset & Identity * **Pool Version:** Select the latest verified version (currently **v3.1**). * **Underlying Asset:** Select the token lenders will deposit (e.g., USDC). * **Price Feed:** Select the Oracle feed used to value this asset. * **Market Name:** A descriptive name for your dashboard (e.g., "USDC Core Market"). 2 ## Global Capacity (Total Debt Limit) Max amount of underlying token that can be borrowed from entire pool. * **Tip:** Setting this higher than your immediate target TVL will help to avoid frequent updates. * *Note:* You will set more granular limits for specific strategies later. 3 ### Interest Rate Model (The Cost Engine) The IRM determines the base borrowing rate based on pool utilization. Gearbox uses a **Two-Kink Model** to create a stable "Optimal Zone" for utilization. **Key Parameters:** * **U1 (Optimal Low):** The start of your target utilization range. * **U2 (Optimal High):** The end of your target utilization range. * **R\_base:** The interest rate at 0% utilization (The minimum cost of capital). * **R\_slope1 / R\_slope2:** The rate increase as utilization rises to U1 and U2. * **R\_slope3 (Penalty):** The sharp rate spike after U2. This forces borrowers to repay if liquidity becomes scarce. **Strategy Tip:** A common approach is to target **80-85% utilization**. Set the borrow rate at this level to be roughly **60-70% of the expected yield** of the collateral strategies. This leaves a healthy spread for borrowers while attracting lenders.\ **Important: The Curator Fee is additive.**\ The Interest Fee (curator's & DAO's revenue) is charged **on top** of the rate paid to lenders. *Example:* If the IRM rate is **5%** and your Interest Fee is **20%**, the borrower pays **6%** total (5% to LPs + 1% Fee). Ensure your IRM leaves room for this markup while remaining competitive. * ***Reference:*** * [Desmos IRM visualizer](https://www.desmos.com/calculator/d281eeb4a9) * [Mainnet ETH pool](https://app.gearbox.fi/pools/0xda0002859b2d05f66a753d8241fcde8623f26f4f/utilization) * [Mainnet USDC pool](https://app.gearbox.fi/pools/0xda00000035fef4082f78def6a8903bee419fbf8e) 4 ## Rate Governance (The "Tumbler") This determines how you manage **Collateral-Specific Rates** (add-on fees for specific collaterals of increased demand). * **Type:** Select **Tumbler**. This allows the Risk Curator to manually update rates as needed. * **Epoch Length:** The mandatory waiting period between rate updates. * *Example:* If set to **2 days**, you can only adjust rates once every 48 hours. This gives borrowers predictability. 5 ### Safety (Loss Policy) This defines the logic for handling "Bad Debt" (when a position is insolvent even after liquidation). * **Policy Type:** Select **Aliased**. * **Function:** This protects Liquidity Providers during market de-pegs. If the market price of a collateral crashes (e.g., a flash crash), the system can switch to a "Fundamental Price" (e.g., Exchange Rate) to prevent selling collateral at a massive loss, effectively pausing liquidations until the market stabilizes. ## Next Steps The Liquidity Pool is now deployed. However, users cannot borrow yet because there are no **Strategies** (Credit Managers) attached to it. ## Execute transactions onchain Source: https://docs.gearbox.finance/curators/execute-transactions-onchain File: content/curators/execute-transactions-onchain.mdx This is the final step. With the market configured, parameters verified, and user experience tested, the changes are ready to be pushed to the live blockchain. ## The Timelock Lifecycle Gearbox governance enforces a **24-hour Timelock** on all critical changes. This security feature provides users time to exit if they disagree with a parameter change. Deployment consists of two distinct actions: 1. **Queue (Propose):** Submit the transaction to the Timelock contract. The 24-hour countdown begins. 2. **Execute (Apply):** After the countdown ends, submit a second transaction to apply the changes. 1 ## Finalize the Proposal Navigate to the GIP page in the interface. 1. **Finalize:** Click **"Finalize GIP"**. This locks the configuration and prepares the transaction data. 2. **Set Earliest Execution Date:** * The default timelock is 24 hours. * **Calculation:** `Current Time + Signing Buffer + 24 Hours`. * *Recommendation:* Add a buffer (e.g., 2 hours) to allow sufficient time for collecting signatures from multisig signers before the target execution time. **Troubleshooting:** If last-minute edits are required, click **"Reopen for Changes"**. Re-finalization is required after editing. ![Figure](https://docs.gearbox.finance/assets/docs/curators/execute-transactions-onchain/01-finalize-the-proposal.png) 2 ## Queue the Transaction The interface generates a link to the **Permissionless Safe App**. 1. Click the link to open the Safe App. 2. **Sign & Submit:** Execute the transaction in the Safe. This initiates the onchain timer. ![Figure](https://docs.gearbox.finance/assets/docs/curators/execute-transactions-onchain/02-queue-the-transaction.png) ### Queueing video walkthrough []() 3 ## Execute (After 24 Hours) Once the timelock expires: 1. Return to the **Permissionless Safe App**. 2. **Sign & Submit:** Execute the final transaction. ### Execution video walkthrough []()
Learn more: Transaction lifecycle details ![Figure](https://docs.gearbox.finance/assets/docs/curators/execute-transactions-onchain/03-timeline.png)
### Deployment Complete The market is now live on the blockchain. * **New Pools:** Lenders can deposit assets. * **New Strategies:** Borrowers can open Credit Accounts. **Requirement:** Ensure the frontend PRs have been merged so users can view the new market and strategies in the app. * Review [frontend listing guide](https://docs.gearbox.finance/curators/listing-a-new-asset-in-the-main-app). ## Claim accrued fees Source: https://docs.gearbox.finance/curators/claim-accrued-fees File: content/curators/claim-accrued-fees.mdx Unclaimed fees sit in the protocol and act as a first line of defense against bad debt. If a liquidation results in a loss, the protocol can burn these accrued fees to cover the deficit before touching the Liquidity Pool. 1 ## Initiate a Proposal Navigate to the **Permissionless Interface**. 1. Click **"New GIP"** (or select an existing draft). 2. Select the **Market** you want to claim fees from. Then select a market you want to claim fees for. 2 ## Add Distribution Action 1. Go to the **Details** tab of the Market. 2. Locate the **Accrued Fees** section. 3. Click the **"Distribute"** button. * *Note:* This adds a transaction to your GIP batch. It does not execute immediately. ![Figure](https://docs.gearbox.finance/assets/docs/curators/claim-accrued-fees/01-add-distribution-action.png) 3 ## Execute via Timelock Like all governance actions, claiming fees is subject to the standard proposal lifecycle. 1. **Finalize** the GIP. 2. **Queue** the transaction in your Safe (starts the 24h timelock). 3. **Execute** the transaction after the timelock expires. Once executed, the funds will appear in your Fee Collector wallet. ## Create Credit Manager Source: https://docs.gearbox.finance/curators/create-credit-manager File: content/curators/create-credit-manager.mdx 1 ## Name Name can reflect the properties of collaterals and position size: * Volatile/ Correlated * Blue-chip/ Experimental * Small/ Medium/ Big (depending on account debt limit) Simple notation is calling naming it with tiers: Tier 1; Tier 2; Tier 3\ Higher tier means larger positions and safer collaterals. 2 ## **Interest Fee** % of borrowing interest taken by DAO and Curator\ Default fee split is 50/50 between DAO and Curator Interest fee of a Credit Manager ***can’t be changed*** after it’s deployed. Curator's fee is added ***on top of interest paid*** by borrower.\ If the IRM + [collateral-specific rate](https://docs.gearbox.finance/core/interest-rate-model#total-cost-of-capital) is 5% and the fee is 20% of the interest, then borrowers pay 6%. Interest fee & Credit Manager's debt limit can be used to ***bootstrap Market utilization.*** e.g. Create Credit Manager with limit of 5,000,000 USD and Interest Fee of 0% can be created to incentivize first borrowers as they will get more favorable borrow rates. 3 ## Liquidation Premium & Fee * **Premium -** % of liquidated collateral taken by liquidator Liquidation premium & fee of a credit manager can’t be modified after it’s deployed. * **Fee -** % of liquidated collateral taken by DAO and Curator It’s not recommended to set liquidation fee to be lower than 0.01%. If the fee is set to 0, then account that fully consists of leveraged underlying token will create bad debt upon liquidation. There is no impact of liquidation fee on the safety of liquidations (it doesn't increase or decrease probability of succesfull liquidations with profit). Borrower loses Liquidation Premium + Liquidation Fee from liquidation collateral. Expired liquidation premium and fee are useful only if Credit Manager is expirable, which is a rare case, so you can freely omit that parameters.\ If set, "Expired" versions of liquidation premium and fee are applied after Credit Manager expiration. 4 ## Minimum debt, Maximum debt, Max. enabled tokens * **Minimum & Maximum debt** - Credit account created in this Credit Manager can't have debt less than minimum and more than maximum. * **Max. enabled tokens** - maximal amount of different tokens that can be counted towards account value (used as cross-collateral margin). **maxDebt/minDebt <= 100/max enabled tokens**\ \ \&#xNAN;*Example: If max enabled tokens = 4 and minimum debt = 10k USDC, maximum debt can't be larger than 250k USDC.* 5 ## Whitelist policy, Expiration **Whitelist** - Require an account-opening allowance from approved borrowers. See [Borrower Allowlisting](https://docs.gearbox.finance/curators/borrower-allowlisting). **Expiration** - Credit Manager can be shut down following specified schedule. May be useful for time-sensitive types of collaterals. 6 ## Total Debt Limit Maximal sum debt on all credit accounts created in this Credit Manager. Interest fee & Credit Manager's debt limit can be used to ***bootstrap Market utilization.*** e.g. Create Credit Manager with limit of 5,000,000 USD and Interest Fee of 0% can be created to incentivize first borrowers as they will get more favorable borrow rates. ## Configure Credit Manager Source: https://docs.gearbox.finance/curators/configure-credit-manager File: content/curators/configure-credit-manager.mdx ## ***Setup examples*** [setup example (BNB chain: USD1 pool, USDX collateral)](https://www.notion.so/Adapter-setup-example-BNB-chain-USD1-pool-USDX-collateral-208145c16224807fa1a0d318c01bc1ae?pvs=21) [setup example (Ethereum chain: tBTC pool, uptBTC collateral)](https://www.notion.so/Adapter-setup-example-Ethereum-chain-tBTC-pool-uptBTC-collateral-20e145c1622480c886d8d43dc5e9f5bb?pvs=21) [setup example (Ethereum chain: USDC pool, frxUSD/USDf collateral)](https://gearboxprotocol.notion.site/Adapter-setup-example-Ethereum-chain-USDC-pool-frxUSD-USDf-collateral-24c145c16224809d80d2d171e1128317?source=copy_link) ## ***Collaterals*** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-credit-manager/01-collaterals.png) 1 ### ***Add new collateral*** Select token from those already added to Market. If not present, [add token to Market.](https://docs.gearbox.finance/curators/configure-market#add-new-asset-and-set-main-feed) Set LT of a collateral - Liquidation Threshold (same as Liquidation LTV on other lending protocols) LT can't be higher than 100% - liquidation Fee - liquidation Premium 2 ### Modify LT of existing collateral To protect borrowers from immediate liquidations, LT can't be changed immediately.\ LT ramping makes LT linearly change current LT to target LT over a specified period. The minimal Ramp duration is 2 days (172800 seconds). Ramp starts when transactions are executed onchain (duration of ramp can be set in UI). ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-credit-manager/02-modify-lt-of-existing-collateral.png) ## ***Adapters*** [***Detailed section on adapters configuration.***](https://docs.gearbox.finance/curators/configure-adapters) ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-credit-manager/03-adapters.png) ## Key concepts & system overview Source: https://docs.gearbox.finance/curators/key-concepts-system-overview File: content/curators/key-concepts-system-overview.mdx With permissionless architecture Gearbox has became even more composable, evolving into a techical stack that allows growing lending businesses, developing DeFi ecosystems and deploy lending markets on any chain by enyone having interest and capacity to do so. is the entrypoint for no-code deployment, curation and collaboration with Gearbox. ## What is permissionless? Anyone can deploy Market Configurator to create and manage Gearbox Markets without needing governance approval. ## What is Gearbox Market? Gearbox Market is a set of modular contracts allowing to facilitate lending, borrowing and productive usage of collaterals at rules set by Curator.\ Properties of a single market include but are not limited to Underlying Token, its Price Feed, Interest Rate Model, collateral-specific Limits and Additional Rates. ## What is Gearbox Instance? **Instance** = **Chain ID** activated by DAO for deployment + Chain-specific address of **DAO Treasury** + **Instance Owne**r multisig that helps configure chain-specific parameters but can't affect Markets configuration. ## What can curator change? The Curator can adjust all Market parameters, with a mandatory 24-hour timelock enforced at the smart-contract level for any changes. ## What is possible with permissionless curation? Each market consists of tens of contracts, including Pool, Oracle, IRM, Loss policy, Credit Managers and Adapters. Such modular architecture allows creating products with market-best flexibility and granular parametrization making Gearbox Protocol the premier platform for crafting sophisticated financial products that address specific market demands and drive long-term value creation. Below is a diagram of the contracts and parameters that a curator can configure, so you can get an idea of how detailed market configuration can be. ![Figure](https://docs.gearbox.finance/assets/docs/curators/key-concepts-system-overview/01-system.png) ## Curator's operations Source: https://docs.gearbox.finance/curators/curator-s-operations File: content/curators/curator-s-operations.mdx Morpho has pioneered the concept of curated lending markets in DeFi, but its approach differs significantly from Gearbox's model. Below is a clear comparison of how curators function in each protocol: ## Morpho: Active Capital Allocation In Morpho, curators are active capital allocators. They: * Distribute depositors' funds across various yield-generating markets. * Operate within markets defined by immutable parameters, such as Loan-to-Value (LTV) ratios and oracles. ## Gearbox: Risk Parameter Management In Gearbox, curators have a more limited role, focusing solely on risk management. They: * Set risk parameters for markets, such as LTV ratios or liquidation thresholds. * Have no authority to move or allocate depositors' funds, which remain under user or protocol control. | Action | Gearbox | Morpho | | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Add exposure to new collateral |
  1. Set collateral limit, LTV and oracle for a new token in Market
  2. Borrowers can now use pool's liquidity
|
  1. Add nonzero supply cap for existing market (LTV and oracle are pre-configured)
  2. Deposit vault's funds to the new market
  3. Borrowers can now use vault's liquidity
| | Modify collateral LTV or Price Feed |
  1. Set new price feed
  2. Start ramp of LTV to target value
  3. Feed & LTV for old and new borrowers are changed
|
  1. Deploy a market with needed LTV and oracle and set nonzero supply cap for it
  2. Feed & LTV are changed only for new borrowers
  3. Start withdrawing liquidity from old market & push borrowers out by raising rate
| | Increase/decrease collateral-specific borrow rate |
  1. Set a new collateral-specific rate in addition to IRM utilization rate
|
  1. Move vault's allocation in/out of the Market to move dynamic IRM
| | Enable 1-click leverage for a collateral |
  1. Allow the list of needed adapters in the Market
|
  1. Contact contango or another strategy provider to integrate your collateral
| ## Curation plans Source: https://docs.gearbox.finance/curators/curation-plans File: content/curators/curation-plans.mdx This page does not impose any access restrictions. Instead, it serves as a guide for Curators, helping them navigate the process of building a lending business on Gearbox and making effective use of the technical stack built around permissionless contracts. The Gearbox Permissionless Governance contracts are designed to enable non-custodial use by anyone interested. The "tariffs" below serve only as an analogy to guide Curators in choosing the level of autonomy and customization that fits their goals, whether it's testing business ideas, expanding into new markets quickly, or fine-tuning every critical detail. ## Codebase usage | Feature | Basic | Professional | Enterprise | |---------|:-----:|:------------:|:----------:| | Build transactions to Create and Configure Markets using [Permissionless Interface](https://permissionless.gearbox.foundation/curators/) (PI), using all the Gearbox contracts that were signed by auditors in Bytecode Repository | ✅ | ✅ | ✅ | | Use Gearbox testing suite to simulate the state, test transactions and Front-End before launching Markets in production | ✅ | ✅ | ✅ | | Request additional integrations (adapters, price feeds) from Gearbox core developers | | ✅ | ✅ | | Develop and audit new pieces of code for specific needs | | | ✅ | ## Front-end | Feature | Basic | Professional | Enterprise | |---------|:-----:|:------------:|:----------:| | Get your personal Curator's domain (your_curator.gearbox.fi) | ✅ | ✅ | ✅ | | Get your Market and Strategies featured on app.gearbox.fi | | ✅ | ✅ | | Host your own version of Gearbox Front-end | | | ✅ | ## Fee sharing and Liquidity Mining incentives | Feature | Basic | Professional | Enterprise | |---------|:-----:|:------------:|:----------:| | Receive 50% of fees generated by curated markets | ✅ | ✅ | ✅ | | Receive $GEAR LM incentives for the Markets' deposits | | ✅ | ✅ | | Negotiate specific fee/token sharing with DAO | | | ✅ | ## Monitoring tools and Emergency permissions | Feature | Basic | Professional | Enterprise | |---------|:-----:|:------------:|:----------:| | Use Gearbox monitoring services to keep an eye on critical metrics (Optimistic Liquidator, Insolvency Monitor) or connect external products (Hypernative, etc.) | ✅ | ✅ | ✅ | | Use Emergency and Loss liquidators maintained by Gearbox core developers | ✅ | ✅ | ✅ | | Run own monitoring tools and liquidators | | ✅ | ✅ | ## Tooling for curators Source: https://docs.gearbox.finance/curators/tooling-for-curators File: content/curators/tooling-for-curators.mdx ## Essential tooling for curators Gearbox goes beyond providing just a protocol by offering a complete ecosystem of tools tailored for curators. These tools enable: * **Market Configuration**: Safely set up and manage lending markets with intuitive interfaces. * **Transaction Integrity**: Ensure the accuracy and security of transactions before they are executed onchain. * **Pre-Deployment Testing**: Test changes in a controlled environment to validate configurations and prevent errors. * **Multi-Chain Support**: Operate seamlessly on almost any EVM-compatible blockchain. ### Curation Supply Chain The curation supply chain in Gearbox is supported by a set of specialized tools designed to streamline market deployment and transaction management while prioritizing security and transparency. **Permissionless Interface** * **URL**: * **Purpose**: Enables curators to create transaction batches for market deployment and configuration using human-readable tables. The interface generates transaction data, which is uploaded to IPFS, with the Content Identifier (CID) signed by the GIP creator to prevent phishing. * **Note**: This interface can't modify onchain state directly; it consists both of a frontend and backend maintained by Gearbox contributors. Therefore it shouldn't be perceived as a final source of truth for onchain state or actions. ![Figure](https://docs.gearbox.finance/assets/docs/curators/tooling-for-curators/01-curation-supply-chain.png) **Permissionless Safe** * **URL:** [**https://safe.gearbox.finance/**](https://safe.gearbox.finance/) * **Repository**: * **Purpose**: An open-source, IPFS-hosted version of the Safe Multisig UI designed to review and sign transactions securely in a human-readable format. It eliminates backend dependencies to mitigate risks like Bybit-type attacks and performs checks of IPFS CID signature to prevent phishing. * **Note**: The open-source nature and IPFS hosting ensure users can verify the code's integrity. ![Figure](https://docs.gearbox.finance/assets/docs/curators/tooling-for-curators/02-curation-supply-chain.png) **Anvil Fork-Based Simulations** * **Purpose**: A unique Gearbox service that allows curators to test market configurations and transaction changes on a fork of the blockchain before onchain execution. This ensures the correctness of state changes and supports testing of various Gearbox components, including liquidators, routers, and frontends. ![Figure](https://docs.gearbox.finance/assets/docs/curators/tooling-for-curators/03-curation-supply-chain.png) ## Create a new Curator (Market Configurator) Source: https://docs.gearbox.finance/curators/create-a-new-curator-market-configurator File: content/curators/create-a-new-curator-market-configurator.mdx The **Market Configurator** serves as the central administration contract for a lending business. It acts as the root permission node. From this single point of control, Curators deploy new markets, adjust risk parameters, and manage fee distribution. This contract must be deployed once per blockchain network. ## Prerequisites **Separation of Drafting vs. Signing** The Gearbox Curation Interface is a **drafting tool**, not a signing terminal. * **Drafting:** You may connect **any** standard wallet (e.g., a hot wallet) to the Gearbox UI to configure parameters and generate transaction files. * **Signing:** The actual execution happens securely within the Gearbox Safe interface () * **Benefit:** Operations teams can draft complex updates without requiring the Admin/Signers to connect their high-security wallets to the web interface. **Recommendation for MPC Users (Fordefi, Fireblocks, etc.)** Institutional MPC wallets often lack direct support for batch transaction builders. * **Recommendation:** Deploy a **1/1 Safe Multisig** with your MPC address as the sole signer. * **Why:** This acts as a compatibility layer, allowing you to utilize the Gearbox Safe interface and transaction batching flow while retaining the custody security of your MPC provider. ## Deployment walkthrough **Access the Interface:** [https://permissionless.gearbox.foundation/curators](https://www.google.com/url?sa=E\&q=https%3A%2F%2Fpermissionless.gearbox.foundation%2Fcurators) []() 1 ## Define Governance Roles * **Admin Address:** * *Function:* Primary governance. Can modify all parameters subject to a **24-hour timelock**. * *Recommendation:* Main Safe Multisig (or 1/1 Safe for MPC users). * **Emergency Admin:** * *Function:* Crisis response. Can disable specific tokens and perform limited list of emergency actions instantly (bypassing timelock). * *Recommendation:* A separate Security Multisig or secure Hardware Wallet. * **Fee Collector:** * *Function:* Revenue destination. Receives all accrued interest and liquidation fees. * **Transaction Format:** * Select **SAFE** to generate a compatible JSON file.
UI walkthrough ![Figure](https://docs.gearbox.finance/assets/docs/curators/create-a-new-curator-market-configurator/01-define-governance-roles.png) ![Figure](https://docs.gearbox.finance/assets/docs/curators/create-a-new-curator-market-configurator/02-define-governance-roles.png)
2 ### Execute transactions in Safe UI The interface generates a JSON file containing the deployment bytecode. 1. Navigate to the **Safe App** (using the Admin wallet defined in Step 1). 2. Open the **Transaction Builder** application. 3. Upload the generated JSON file. 4. Review the transaction details and execute.
UI walkthrough ![Figure](https://docs.gearbox.finance/assets/docs/curators/create-a-new-curator-market-configurator/03-execute-transactions-in-safe-ui.png) ![Figure](https://docs.gearbox.finance/assets/docs/curators/create-a-new-curator-market-configurator/04-execute-transactions-in-safe-ui.png)
3 #### Sync Permissionless Interface Once the transaction is confirmed onchain, the Gearbox interface must index the new Configurator. 1. Navigate to the **Instances Page** on the Gearbox UI. 2. Select the relevant chain and click **Sync**. 3. Wait for the sync to complete. The new Market Configurator will appear in the dashboard.
UI walkthrough On Instances Page click on a chain where you've deployed Market Configurator ![Figure](https://docs.gearbox.finance/assets/docs/curators/create-a-new-curator-market-configurator/05-sync-permissionless-interface.png) Click on a Sync button and wait for Sync to end ![Figure](https://docs.gearbox.finance/assets/docs/curators/create-a-new-curator-market-configurator/06-sync-permissionless-interface.png)
### Next Steps With the Market Configurator deployed, the infrastructure is ready for the first lending Market. ## Allow leverage strategies Source: https://docs.gearbox.finance/curators/allow-leverage-strategies File: content/curators/allow-leverage-strategies.mdx ## What is a strategy? A **Strategy** (technically a "Credit Manager") is a specific credit product offered to borrowers. While the Pool holds the liquidity, the Strategy defines **how that liquidity can be used**. * *Example 1:* "Stablecoin Farming" (Low Risk, High LTV, Whitelisted Stablecoins only). * *Example 2:* "Memecoin Trading" (High Risk, Low LTV, Wide asset list). You can attach multiple Strategies to a single Pool, allowing to segment risk and offer different terms for different user behaviors. ## Prerequisites: The Strategy Library To make setup easy, Gearbox uses **Strategy Bundles**. These are pre-configured "recipes" organized by the **Collateral Token** you want to support. **How to check availability:** 1. Open the **New Strategy** tab in the interface. 2. **Search for the Target Token** you want users to leverage (e.g., search for `wstETH` or `sUSDe`). 3. **If the token appears:** A Strategy Bundle exists. Selecting it will automatically configure the necessary smart contract connections (Adapters) to enable leverage for that asset. 4. **If the token is missing:** A bundle for this specific asset hasn't been created yet. * *Action:* Contact Gearbox Contributors to request a new Strategy Bundle. ### How to add and configure a strategy 1 ## Click on a "New Strategy" tab ![Figure](https://docs.gearbox.finance/assets/docs/curators/allow-leverage-strategies/01-click-on-a-new-strategy-tab.png) 2 ## Select Strategy Search for your Target Token to allow leverage on. * *Note:* The bundle automatically handles the complex technical setup (Adapter configuration), so you only need to focus on the financial parameters. ![Figure](https://docs.gearbox.finance/assets/docs/curators/allow-leverage-strategies/02-select-strategy.png) **Liquidation Threshold (LT)**\ This determines the maximum leverage. * *Formula:* `Max Leverage = 1 / (1 - LT)` * *Example:* LT 90% = 10x Leverage. LT 80% = 5x Leverage. **Interest Fee (Revenue)**\ The percentage of the borrowing interest that is captured as revenue. * *Split:* By default, this fee is split 50/50 between Curator and the Gearbox DAO. * *Impact:* This is charged **on top** of the base rate. If the base rate is 5% and your fee is 20%, the borrower pays 6%. **Important:** In the current version, the Interest Fee percentage is fixed upon deployment. To change it later, you must deploy a new Credit Manager. **Growth Hack:** Set a **0% Interest Fee** initially to attract early users with cheaper rates, then launch a new "Premium" strategy later once you have traction. 3 ## Liquidation Economics These parameters ensure the system remains solvent by incentivizing third-party liquidators. **Liquidation Premium (The Bounty)**\ The percentage of collateral given to the liquidator as a reward. **Liquidation Fee (The Penalty)**\ The percentage of collateral taken by the Protocol (You + DAO) during a liquidation. **Risk Management Intuition:**\ The Liquidation Premium is not just a "fee", it is the **incentive** for liquidators to keep the protocol solvent by forcefully exchanging Collateral token for the Debt token.\ For the liquidations to happen organically, it must take multiple factors into account: 1. **Slippage:** The cost of selling the collateral on a DEX. 2. **Gas Costs:** The transaction fee to execute the liquidation. 3. **Time value of money + collateral risk:** If the asset is illiquid and/or has timelocked redemptions, liquidator will have to hold the collateral through redemption cycle. 4. **Oracle reliability:** Lending market values collateral by the oracle price, however "true" value at every given moment can differ with magnitude defined by oracle methodology and market conditions. 4 ## Position Limits **Min & Max Debt**\ Defines the size of accounts allowed in this strategy. * *Min Debt:* Must be high enough to cover gas costs for liquidators. (e.g., $10,000+ on Ethereum Mainnet). * *Max Debt:* Limits exposure to a single whale. **Max Enabled Tokens**\ The maximum number of different tokens a user can hold as collateral simultaneously. * *Rule of Thumb:* Keep this number low (1) for efficiency. In practice, users rarely use more than 1 unique collateral token. **Technical Constraint:**\ The protocol enforces a ratio between your debt limits and the token count to ensure liquidations are always mathematically possible. **Formula:** `maxDebt / minDebt <= 100 / maxEnabledTokens` *Example:* If you allow **4 tokens**, the ratio `100/4 = 25`. Therefore, your Max Debt cannot be more than **25x** your Min Debt.\ \&#xNAN;*(If Min Debt = 10k, Max Debt must be <= 250k).* 5 ## Lifecycle (Optional) If you are running a fixed-term lending product (e.g., a "Season 1" pool or a bond-like structure), you can configure expiration settings. **Expiration Date**\ The timestamp after which the strategy winds down. * *Behavior:* After this date, **all** accounts can be liquidated, regardless of their Health Factor. Borrowing is disabled. **Expired Premium & Fee**\ You can set different liquidation penalties that apply *only* after the expiration date. * *Use Case:* Usually set lower than standard penalties to minimize users' losses if market conditions allow it. 6 ### Review & Deploy Review the configuration summary. ![Figure](https://docs.gearbox.finance/assets/docs/curators/allow-leverage-strategies/03-review-and-deploy.png) ### Next Steps Now you need to ensure that the resulting market state matches with the expectations. The best way to do it is to simulate execution of the real transactions on chain fork. The Testing section will show how to do it. ## Verify & Simulate Source: https://docs.gearbox.finance/curators/verify-simulate File: content/curators/verify-simulate.mdx Before executing any transaction on the mainnet (which costs gas, time and operations), it's better to verify that configuration works as intended. Gearbox provides a **Simulation Service** (Fork Testing). The system spins up a temporary "Sandbox" copy of the blockchain, applies your changes, and runs a list of tests. ## Automated Safety Checks The simulation runs a suite of automated checks to ensure your parameters are safe and functional. You should review the output of these tests (typically provided in the GIP report or Interface). ## The "Staging" App (User Experience Test) Automated tests check the math, but they don't check the experience. The simulation service generates a temporary **Staging Frontend** connected to the Sandbox fork. **Action:** Open the Staging App link and act as a user. 1. **Connect Wallet:** Use a test wallet (the fork will impersonate your tokens). 2. **Open a Position:** Try to borrow funds using your new strategy. 3. **Execute a Trade:** Try to swap assets or deposit into a vault via the adapter. 4. **Close/Repay:** Ensure you can exit the position. **After the fork has been created and the tests have passed, you can open the App connected to the test blockchain state.** ![Figure](https://docs.gearbox.finance/assets/docs/curators/verify-simulate/01-the-staging-app-user-experience-test.png) ### Application test walkthrough []() ## Prepare the Main Interface Once the contracts are deployed, they exist on the blockchain, but the official Gearbox Interface (app.gearbox.finance) may not know the imporant data: token icon, collateral APY, the list of points earned by borrowers or suppliers. For the tokens and strategies to be supported by the app, ensure that frontend configuration has all the required data: [listing-a-new-asset-in-the-main-app](https://docs.gearbox.finance/curators/listing-a-new-asset-in-the-main-app) ## Next Steps If the simulations pass and the UI looks correct, you are ready to execute the transactions onchain. ## Price feeds' configuration Source: https://docs.gearbox.finance/curators/price-feeds-configuration File: content/curators/price-feeds-configuration.mdx The feeds configurations are reviewed at . It requires CID of txs file uploaded to IPFS. ![Figure](https://docs.gearbox.finance/assets/docs/curators/price-feeds-configuration/01-price-feeds-configuration.png) ## TL;DR (Actionable checklist) 1. Txs simulation must pass. Click on Simulate button next to each batch to check. 2. Check the displayed price in the multisig UI to adequatly match current market values 1. Review allowPriceFeed transactions. 2. Grab the token address and verify its price on a DEX aggregator () 3. If not tradable on aggregators, ask the proposer for the correct reference (e.g. Pendle UI for PTs, Curve UI for LP tokens, or the issuer’s app for derivatives/vaults) 4. Zero price feed (always returns $0) can be safely added to any token for compatibility. 3. Check staleness period of the feed 1. Pull feeds → 4 min staleness 2. Push feeds → Heartbeat + 15 min (Ethereum) / Heartbeat + 2 min (L2s & faster chains). 4. Check that the feed contract is verified 1. Confirm verification on the chain’s block explorer. 5. Check that feeds are adequately capped from above: 1. Stablecoin feeds are capped by $1.04 from above 2. PT feeds for dollar-pegged vaults are capped by $1 from above 6. If the feed is deployed from external factory, it should use no Pull feeds as underlying feeds of factory deployment. ⚠️ If any of these criteria aren’t met: don’t sign, ask in chat for clarification. ✅ For a setLimiter transactions it's enough to check that simulation passes. This action updates exchange rate bounds of LP price feeds, and its correctness is checked on a contract level. *** ### 1) Purpose & Scope These Terms & Conditions define the minimum due‑diligence and neutral‑gatekeeping standards for IO signers when **adding, configuring, or allowing** price feeds in the **Price Feed Store (PFS)** on any supported EVM chain. The sole goal is to ensure that, **at the moment of signing**, every configured feed **returns an adequate market price for the intended token, normalized to 8 decimals**, and satisfies staleness / quality constraints. > Scope explicitly excludes any market‑risk, business, or curation decisions. IO signers act only as neutral technical gatekeepers. *** ### 2) Authority, Membership & Neutrality (summary) * **Authority (PFS):** IO may add/remove feeds; set staleness period; attach/detach feeds to tokens; and run feed configuration calls required by integrated providers. * **Neutrality:** IO remains **business-neutral**. Decisions must be based **only on objective technical criteria** below. All valid, safe requests should be processed in a reasonable timeframe. * **Non‑interference with markets:** PFS changes **do not alter behavior of existing Markets by themselves** and **are not auto‑applied** to them. *** ### 3) Definitions & Expectations * **Price Feed Store (PFS):** Chain‑specific registry of tokens and feeds. A token can be used as collateral only after its token entry and at least one allowed feed are present. * **8‑decimal normalization:** All effective Gearbox price feeds **must return USD‑denominated prices with 8 decimals** (`1e8` scale). Signers should verify output scale when checking a feed. * **Staleness Period:** Maximum allowed time since last update before a feed is considered stale and reverts/invalidates. * **Adequate market price:** A price reasonably close to reputable sources at the time of signing. *** ### 4) Pre‑Signing Due‑Diligence (hard requirements) **Signers must complete all checks below before approving the transaction.** If any check fails, **do not sign.** **4.1 Contract & Deployment** 1. **Feed contract is verified** on a reputable explorer (Etherscan/chain explorer). 2. If the feed is not external, it must be deployed from Bytecode Repository. **4.2 Price Output & Decimals** 1. **Price sanity:** Read the feed (via explorer read panel, provider dashboard, or PFS UI). The value must be **within a reasonable range** of one or more of: 1. **CoinGecko** (or equivalent public index), 2. **Trusted DEX/aggregators** (Uniswap/Curve/Balancer; 1inch/Cow/Odos), 3. **Designated platforms** when public indexes are unavailable (e.g., **Pendle markets** for PTs; **Pyth Insights**; **Redstone App**; protocol UIs for ERC4626 vault exchange rate). 2. **Decimals:** Confirm that the effective price value is **normalized to 8 decimals**. **4.3 Staleness** 1. **Staleness period** must be reasonable for the source and chain: 1. **Pull‑type feeds (e.g., Pyth/Redstone pull):** *recommended* `240s` (4 min) unless documented otherwise. 2. **External Aggregator feeds (push/heartbeat):** heartbeat **+ 15 min** (slower chains, e.g. Ethereum) or **+ 2 min** (faster chains, e.g. L2s). **4.4 Asset‑Specific Parameters (when applicable)** 1. **Stablecoin‑to‑USD feeds:** The observed price should be **bounded from above at 1.04**. 2. **Pegged assets feeds (LST-to-ETH, LRT-to-BTC, cbBTC-to-BTC etc.):** The observed ratio should be **bounded from above at 1.04**. *** ### 5) Refusal Policy If **any** requirement in fails or is inconclusive, **do not sign any transactions**. Examples: * Contract not verified; * Output not 8‑decimals normalized; * Price materially diverges from reputable venues; * Staleness period unreasonable for the source/chain; * Asset‑specific parameters missing/incorrect. *** ## Asset classes Asset class is a pair of (token-specific features, price feed methodology) which defines the behavior of collateral in different market scenarios. The same token can have different risks for LPs/Borrowers if priced differently. All of the tokens can be borrow-only or used as collaterals. \ Consider cases of * Correlated debt/collateral pairs * Volatile debt/collateral pairs Describe the policy of setting reserve feeds and aliased loss policy. Take into account that pull feeds providers (pyth and especially redstone) can be less reliable than push Some of the used feeds can be provided by token issuer itself (for example Resolv PoR, midas feeds etc.) and have no strict update frequency (we've seen Resolv update PoR feeds 2 hours later than was initially stated) 1. Stablecoins/ synthetic dollars\ USDT, USDe, USDai, DAI, USDf etc. 2. ETH or BTC equivalents 1. stETH, tBTC etc 3. Yield-bearing vaults\ Stream.finance xUSD, Midas vaults, tETH, LRTs etc. 1. Priced using ERC4626 feeds 2. Priced using composite feeds (prices can be market-based, exchange rate or PoR) 4. Pendle PT tokens 1. TWAP-based pricing or deterministic feeds 5. Curve, Balancer LP tokens 1. For the tokens having rate oracle or erc4626 vault attached in Curve or Balancer pools, oracle price appreciation is automatically displayed in virtual\_price 6. Pendle LP tokens 1. TWAP-based pricing or deterministic feeds 7. Delayed withdrawal phantom tokens 1. Since delayed withdrawal tokens are not liquidatable, the most favorable setting is when the position's HF is high enough not to fall below 1 due to accrued debt while redemption is being processed.\ \ One of the ways to achieve it is to set reserve feed of withdrawal token to be lower than its Main feed by some percentage. This percentage will effectively enforce the minimal health factor for user to have to initiate delayed withdrawal.\ \ Reserve to main price discount of 2% will mean that user has to maintain HF above \~1.02 to initiate full withdrawal of his collateral. ## Instance activation guidlines Source: https://docs.gearbox.finance/curators/instance-activation-guidlines File: content/curators/instance-activation-guidlines.mdx ## TL;DR (Actionable checklist) 1. Chain's block Gas Limit ≥ 30M (it's possible to execute transaction that uses 30M gas) 2. Canonical safe proxy factory v1.4.1 (0x4e1DCf7AD4e460CfD30791CCC4F9c8a4f820ec67) is verified 3. $GEAR address is either null or can be verified on block explorer to be $GEAR token correctly bridged from Ethereum 4. Wrapped Gas Token address is listed on Chain's docs as canonical 5. Instance Owner Safe Proxy is deployed on target chain and can be verified on block explorer 6. Financial Multisig Safe Proxy is deployed on target chain and can be verified on block explorer ⚠️ If any of these criteria aren’t met: don’t sign, ask in chat for clarification. > Chain sync process involves uploading all the bytecode of used contracts to Bytecode Repository (like onchain github for secure deployment of all the modules)\ \ Here is an example of sync txs on Optimism: \ \ The process is gas- and txs- extensive, and requires \~400M of gas and RPC with 10k blocks per getLogs request. ## Listing a new asset in the main App Source: https://docs.gearbox.finance/curators/listing-a-new-asset-in-the-main-app File: content/curators/listing-a-new-asset-in-the-main-app.mdx Once the market contracts are deployed onchain, the Gearbox Interface (`app.gearbox.fi`) must be updated to display them. The official interface is maintained by Gearbox Contributors. To accelerate the listing process, Curators can submit a **Pull Request (PR)** to the configuration repositories. This provides the development team with the necessary data (icons, addresses, APY sources) in a ready-to-merge format. ## Prerequisites 1. **GitHub Account:** Required to submit changes. 2. **Asset Icons:** High-quality `.svg` files for the underlying token and any reward tokens. 3. **Contract Addresses:** The addresses of the deployed Credit Managers. 4. **APY Data Sources:** Links to DefiLlama or Merkl pools (if applicable). 1 ## Upload Asset Icons **Repository Location:** **Instructions:** * Format: `.svg` (Strict requirement). * Naming: **Lowercase symbol** (e.g., `susde.svg`, `wsteth.svg`).
Asset display example ![Figure](https://docs.gearbox.finance/assets/docs/curators/listing-a-new-asset-in-the-main-app/01-upload-asset-icons.png)
**Merkl Campaigns:** If the strategy earns rewards via Merkl, the reward token icon must also be uploaded, or the APR tooltip will break.
Merkl display example ![Figure](https://docs.gearbox.finance/assets/docs/curators/listing-a-new-asset-in-the-main-app/02-upload-asset-icons.png)
2 ### Configure Lending Pools (Earn Page) If a new Liquidity Pool was deployed, it must be added to the "Earn" page configuration. **Repository Location:** **Fill in the following fields:** * `name`: The displayed name (e.g., "Edge UltraYield USDC"). * `address`: The contract address of the Liquidity Pool. * `chainId`: The integer ID of the network (e.g., `1` for Mainnet, `42161` for Arbitrum). * `network`: The string name of the network (e.g., "Mainnet", "Arbitrum"). * `curator`: The entity managing the pool. * *Constraint:* This must match a valid `Curator` type defined in the [Gearbox SDK](https://github.com/Gearbox-protocol/sdk/blob/master/src/sdk/chain/chains.ts). * `poolType`: The category tag (e.g., `["stable"]`, `["eth"]`). * *Constraint:* This must match a valid pool type defined in the [Pools type list](https://github.com/Gearbox-protocol/static/blob/main/src/core/pools.ts). 3 ### Configure Strategies (Farm Page) If new Credit Managers (Strategies) were deployed, they must be added to the "Farm" page configuration. **Repository Location:** **Fill in the following fields:** * `name`: The display name (e.g., "Lido staked ETH"). * `id`: The token symbol (e.g., "susde"). This serves as the unique key. * `tokenOutAddress`: The address of the collateral token. * `creditManagers`: An array containing the addresses of all Credit Managers that support this strategy. * *Example:* `["0xCM_Address_1", "0xCM_Address_2"]` * `strategyType`: The category tag (e.g., `["stable"]`, `["eth"]`). * *Constraint:* This must match a valid strategy type defined in the [Strategy types list.](https://github.com/Gearbox-protocol/static/blob/main/src/core/strategy.ts) * `issuesOnClose`: Set to `true` if the asset has delayed redemptions or requires extra capital to close (prevents users from getting stuck). 4 ## Connect Yield Data (APY) ### Option A: DefiLlama Integration If the underlying protocol is tracked on DefiLlama. **Repository Location:** * **Action:** Add the DefiLlama Pool ID to the configuration map. #### Option B: Merkl Integration If the strategy earns incentives via Merkl. **Repository Location:** * **Action:** Add the Merkl Campaign parameters to the relevant Network object (e.g., `Plasma`, `Monad`). * **Key:** The token address (e.g., `"0x2d84..."`). * **Value Object:** * `id`: The token address(repeated). * `symbol`: Token symbol (e.g., `"USDT0USDe"`). * `type`: Usually `"common"`. #### Option C: Points Campaigns If the strategy or pool earns points (e.g., Ethena Sats, EigenLayer Points), the configuration is split into three parts. **1. Register the Point Type**\ If this is a new point system, define it in the base configuration. * [**Path**](https://github.com/Gearbox-protocol/apy-server/blob/92bf265744b95ecf7ce85da67278b27a71229691/src/tokens/points/constants.ts#L58) * **Action:** Add a new entry to `REWARDS_BASE_INFO`. ```typescript somnia: (multiplier: PointsReward["multiplier"]): PointsReward => ({ name: "Somnia", units: "points multiplier", multiplier, type: "somnia", }), ``` **2. Apply to Strategies (Farm Page)**\ If the points are earned by holding collateral (e.g., weETH). * [**Path**](https://github.com/Gearbox-protocol/apy-server/blob/92bf265744b95ecf7ce85da67278b27a71229691/src/tokens/points/constants.ts#L276C14-L285C7) * **Action:** Add the collateral address to `POINTS_INFO_BY_NETWORK`. ```typescript { address: "0xCollateralAddress...", symbol: "weETH", rewards: [REWARDS_BASE_INFO.etherfi(200n)], // 200n = 2x Multiplier }, ``` **3. Apply to Pools (Earn Page)**\ If the points are earned by depositing into a lending pool. * **File:** * **Action:** 1. Add the Pool Address to `const POOLS`. 2. Add the Token Address to `const TOKENS`. 3. Add the Reward Logic to the Network array. ```typescript { pool: POOLS.USDC_E_V3_SOMNIA, token: TOKENS.USDC_E_SOMNIA, symbol: "USDC.e", amount: 12n * 1000n, // 12n * 1000n = 1.2x Multiplier duration: "day", name: `${REWARDS_BASE_INFO.somnia(1n).name} ${REWARDS_BASE_INFO.somnia(1n).units}`, type: REWARDS_BASE_INFO.somnia(1n).type, estimation: "absolute", condition: "holding", }, ``` ## Emergency admin Source: https://docs.gearbox.finance/curators/emergency-admin File: content/curators/emergency-admin.mdx UI for executing Emergency Admin function is located at [https://permissionless-safe.gearbox.foundation/emergency/](https://permissionless-safe.gearbox.foundation/emergency/) ## Why is it needed? The Emergency Admin role has a very limited set of actions that can be executed immediately, without a timelock. These actions are designed to let curators respond quickly to incidents and protect the solvency of the market. *** ## How to add an emergency admin? Only one address can have Emergency Admin role. It is set at the moment of creating a Market Configurator. It can be configured in Curators' UI for the existing Market Configurator: []() *** ## What are the available functions, its scope and impact? | Action | New positions | Borrow | Withdraw | Adapter call | Liquidate | |---|---|---|---|---|---| | Token Limit = 0 Impact: Asset (Pool) | ❌ | ⚠️ | ✅ | ✅ | ✅ | | Forbid Adapter Impact: Adapter (CM) | ⚠️ | ✅ | ✅ | ❌ | ⚠️ | | CM debt limit = 0 Impact: CM | ❌ | ⚠️ | ✅ | ✅ | ✅ | | Forbid borrowing Impact: CM | ❌ | ❌ | ✅ | ✅ | ✅ | | Set Main Feed Impact: Asset (Pool) | ✅ | ✅ | ⚠️ | ⚠️ | ⚠️ | | Forbid Token Impact: Collateral (CM) | ❌ | ❌ | ❌ | ❌ | ✅ | | Pause CM Impact: CM | ❌ | ❌ | ❌ | ❌ | ❌ | | Pause Pool Impact: Pool | ❌ | ❌ | ❌ | ❌ | ❌ | *** ## Emergency scenarios
Collateral token incident * **Low severity** *(incident status is unclear)* * **Set token limit = 0** in Pool * Collateral exposure can't be increased * Existing positions operations are not limited * **Medium severity** *(collateral behavior is unhealthy, but no immediate bad debt risk)* * **Forbid token** in Credit Manager * Collateral exposure can't be increased * Existing positions operations are limited * Operations which decrease HF are blocked (increase debt, withdraw collateral, swap into different collateral with lower LT) * Operations which increase balance of forbidden token are blocked * **High severity** *(collateral poses risk to market solvency)* * **Pause** all Credit Managers which have exposure * No user-side operations are allowed * Only emergency liquidators can liquidate accounts
Price feed incident ### **Overpricing token** * **Feed price is higher than market price enough to block liquidations**\ In cases when price feeds deviates from market price by more than liquidation premium, liquidations become unprofitable. * **Low severity** *(existing positions create no insolvency risks)* * Set **Token Limit = 0** in Pool to limit increasing exposure to Asset. * Consider creating a new Credit Manager with higher liquidation premium. * **High severity** *(existing positions create risk to market solvency)* * **Set Main Feed** of token to one that is closer to market value. * This action will reduce Health Factor of existing positions which may result in immediate liquidations. * If the new Main feed is equal to current Reserve feed, reserve feed will be automatically detached from token, which will block operations relying on Safe Price (Collateral withdrawals, Usage of adapters, Partial Liquidations). * **Feed price is higher than market price enough to drain Pool**\ If a price feed exceeds the market price by more than 1/LT of a token, an attacker can repeatedly acquire the token at market price and extract excess Pool liquidity against its inflated oracle valuation.\ \ \&#xNAN;*This risk is mitigated if at least one of Main and Reserve feeds returns adequate value, as the token at risk will be priced at minimal price during collateral withdrawals.* * **High severity** * **Forbid token** in Credit Manager * Collateral exposure can't be increased * Existing positions operations are limited (users can only fully close accounts)
External protocol incident **An external contract that is used through Adapter may appear to be misconfigured, hacked or is a proxy contract having its implementation replaced for an unsafe one.** Call **Forbid Adapter** for every Credit Manager which has the adapter allowed.
### Emergency Methods Definitions **Token‑Specific** **`setTokenLimit(token, 0)`** * **Impact Scope:** Pool * Sets the quota limit for a token to zero. * Users cannot increase quota in that token, meaning new exposure to collateral can't be created. * Withdrawals, debt increases, and adapter calls for existing positions remain enabled. **`forbidToken(token)`** * **Impact Scope:** Credit Manager * Highly ***Restricts allowed operations*** for accounts. * Operations which decrease HF are blocked (increase debt, withdraw collateral, swap into different collateral with lower LT) * Operations which increase balance of forbidden token are blocked * **Liquidations** are not impacted. **Feed‑Specific** **`setMainPriceFeed(token, feed)`** * Switches the main price feed of a token to another feed pre‑approved in the Price Feed Store. * Target feed must have been added at least 1 day earlier. * **Side effects:** * If the new main feed equals the current reserve feed, the reserve feed is removed (token ends up with only one feed). * New main price may be low enough to trigger immediate liquidations of Credit Accounts. **Adapter‑Specific** **`forbidAdapter(adapter)`** * Disables calls through a specific adapter. * Prevents swaps on DEXes, vault deposits/withdrawals, etc. * **Side effects:** * If the forbidden adapter highly contributes to some tokens' liquidity, forbidding it may break liquidations, since most of Gearbox's internal liquidators rely on allowed adapters for searching tokens' swap paths. External liquidators may or may not be affected. **Pool‑Global** **`pausePool(pool)`** * Pauses pool‑level operations (deposit into pool, withdraw LP tokens) * Designed to be combined with Credit Manager pause to prevent bank runs in the most extremal scenarios. **`setCreditManagerDebtLimit(cm, 0)`** * Sets the Credit Manager debt limit to zero. * Prevents new borrowing capacity from the pool into that CM. Existing positions are not affected. **Credit Manager‑Global** **`pauseCreditManager(cm)`** * Pauses all Credit Manager operations. * Borrowing, withdrawing collateral, opening & closing credit accounts, performing adapter calls are blocked. * Only whitelisted **Emergency Liquidators** can liquidate accounts. **`forbidBorrowing(cm)`** * Forbids opening new accounts in the CM. * Prevents increasing debt in existing accounts. **Loss Policy** **`setAccessMode(mode)`** * Adjusts who can execute liquidations which result in bad debt accrual. * Modes must be documented (TBD). **`setChecksEnabled(flag)`** * Enables/disables specific safety checks within loss policy. ## Pausable/Unpausable admin Source: https://docs.gearbox.finance/curators/pausable-unpausable-admin File: content/curators/pausable-unpausable-admin.mdx ## Pausable admin interface Use the [emergency interface](https://permissionless-safe.gearbox.foundation/emergency/) to execute Pausable admin functions. Pausable admin can pause active **Pools** and **Credit Managers.** Unpausable admin can unpause paused **Pools** and **Credit Managers.** > Pausable admin is a sensitive role, but its permissions are softer that unpausable admin.\ \ You can set **pausable admin** to be **EOA** to be able to react quickly, but **unpausable admin should be a multisig**. *** ## Multipause Multipause is a helper contract that allows pausing multiple Market contracts in one transaction. > For multipause contract to function, you need to add a Multipause contract and at least one Pausable admin to the list. ## How to add admins and multipause []() *** *** ## Functions definition **`Pause Pool(pool)`** * Pauses pool‑level operations (deposit into pool, withdraw LP tokens) * Designed to be combined with Credit Manager pause to prevent bank runs in the most extremal scenarios. **`Pause Credit Manager(cm)`** * Pauses all Credit Manager operations. * Borrowing, withdrawing collateral, opening & closing credit accounts, performing adapter calls are blocked. * Only whitelisted **Emergency Liquidators** can liquidate accounts. **`Pause Market (cm)`** * Pause Pool and all Credit Managers of a Market. **`Pause All Contracts (mc)`** * Pause all Pool and all Credit Managers of a Market Configurator. *** ## How to pause contracts Source: https://docs.gearbox.finance/curators/how-to-pause-contracts File: content/curators/how-to-pause-contracts.mdx 1 ## Navigate to emergency dashboard & Select Curator 2 ## Pause needed contracts ![Figure](https://docs.gearbox.finance/assets/docs/curators/how-to-pause-contracts/01-pause-needed-contracts.png) * `Pause CM` * Forbid all operations with credit accounts within a CM * Liquidations are allowed to whitelisted emergency liquidators * `Pause pool` * *Forbid deposits and withdrawals* * `Pause market` * *Pause pool and all CMs* * `Pause all contracts` * *For each market:* * *Pause pool and all CMs* ## How to unpause contracts Source: https://docs.gearbox.finance/curators/how-to-unpause-contracts File: content/curators/how-to-unpause-contracts.mdx ## Unpause Credit Manager 1 ### Open the Credit Manager curator page Go to [permissionless.gearbox.foundation/curators](https://permissionless.gearbox.foundation/curators). 2 ### Create a new GIP, select a Market and go to the paused Credit Manager's page Add unpause transaction and execute GIP ![Figure](https://docs.gearbox.finance/assets/docs/curators/how-to-unpause-contracts/01-create-new-gip-select-market-go-paused-credit-manager.png) ## Unpause Pool 1 ### Open the Pool curator page Go to [permissionless.gearbox.foundation/curators](https://permissionless.gearbox.foundation/curators). 2 ### Create a new GIP, select a Market and go to Details section Add unpause transaction and execute GIP ![Figure](https://docs.gearbox.finance/assets/docs/curators/how-to-unpause-contracts/02-create-new-gip-select-market-go-details-section.png) ## Add required Price Feeds Source: https://docs.gearbox.finance/curators/add-required-price-feeds File: content/curators/add-required-price-feeds.mdx ## Price Feed Store (PFS) The Price Feed Store is a chain-specific registry that lists which tokens and price feeds can be used within Gearbox on that chain. For a token to be used as collateral, it must first be added to the Price Feed Store, along with a list of available price feeds. Only the **Instance Owner**—a chain-specific multisig—can add or update entries in the Price Feed Store. This role acts as a neutral technical gatekeeper, ensuring safe and verified configurations while staying out of risk or business decisions. The Instance Owner multisig is open to participation from active curators and chain contributors, making the process transparent and inclusive without compromising protocol safety. ## How to work with PFS? Interface for accessing each chain's PFS is located at [https://permissionless.gearbox.foundation/instances](https://permissionless.gearbox.foundation/instances/1). **Demo of PFS setup workflow:** []() ## What price feed sources are already integrated? *(Click on feed to see details)* | Price source | Feed type | Supported collaterals & features | |---|---|---| | [Chainlink, Redstone push, EO AggregatorV3Interface - compatible external price providers](https://docs.gearbox.finance/curators/add-required-price-feeds#external-feeds) | External | Blue-chip tokens | | [ERC4626 exchange rate](https://docs.gearbox.finance/curators/add-required-price-feeds#erc4626-exchange-rate) | ERC4626 | Most of the yield-bearing vaults | | [Pyth](https://docs.gearbox.finance/curators/add-required-price-feeds#pyth) | Pyth | Blue chip & emerging tokens | | [Redstone pull](https://docs.gearbox.finance/curators/add-required-price-feeds#redstone-pull) | Redstone | Deployed on any EVM on day 0 | | Upper bound | Bounded | Bound borrowed tokens to protect borrowers from liquidationsBound collateral tokens to protect LPs from price manipulation | | Multiply 2 feeds price | Composite | Optimal way to price correlated token pairs | | Constant price | Constant | Hardcode pegged assetsApply premium or discount combining with composite feed | | [Curve LP](https://docs.gearbox.finance/curators/add-required-price-feeds#curve-stable) | Curve_crypto Curve_stable | Collateralize Curve LP tokens | | Token price from Curve Pool | Curve TWAP | Collateralize experimental tokens with pricing based on DEX trades | | [Pendle PT](https://docs.gearbox.finance/curators/add-required-price-feeds#pendle-pt) | Pendle PT TWAP | Get TWAP market price of PTs | | [Kodiak Island](https://docs.gearbox.finance/curators/add-required-price-feeds#kodiak-island) | Kodiak_island | Get island share price | ## Updatable LP bounds Some tokens in Gearbox are tokenized vault shares — they represent ownership of assets inside a vault or liquidity pool. Examples include: * Vault tokens like ERC-4626 share tokens * LP tokens from DEXs or yield strategies **How pricing works:** * Each share has an exchange rate to its underlying asset (e.g., 1 share = X ETH). * The LP price feed combines: * the share price from the vault, and * the USD price of the underlying asset. **Why bounds are needed:** * Vault share prices can be manipulated or distorted through smart-contract exploits. * Normally, share prices move slowly and predictably with yield — not like volatile traded tokens. **To protect against abnormal price swings, Gearbox sets updatable bounds:** * A minimum and maximum price for each LP share. * These bounds cap sudden drops or spikes in reported prices. * They are updated periodically to track the vault’s real exchange rate as it appreciates over time. This mechanism keeps LP pricing stable, reliable, and manipulation-resistant while still following genuine on-chain growth. *** ## Setup details
Pyth **Click New Feed and select Pyth type** ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/01-setup-details.png) ***Pyth dashboard with feeds info:*** [***https://insights.pyth.network/price-feeds***](https://insights.pyth.network/price-feeds) * Name: * Specify token Symbol and Price methodology * Examples: * Name: RLP (Redemption rate)\ Feed: * Name: RLP (Market)\ Feed: * Token: * Token address\ Needed for Gearbox contracts to understand what pull feed needs to be updated * descriptionTicker * The same as name\ This parameter is to be removed later * priceFeedId ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/02-setup-details.png) * Pyth * Address of Pyth singleton contract on the target chain\ see here: * Ethereum - 0x4305FB66699C3B2702D4d05CF36551390A4c69C6 * Berachain - 0x2880aB155794e7179c9eE2e38200202908C17B43 * Etherlink - 0x2880aB155794e7179c9eE2e38200202908C17B43 * maxConfToPriceRatio (takes value in bps: 300 = 3%) * Except for the current price, Pyth returns confidence interval * If the width of confidence interval in % is larger than this parameter, feed ourput is considered invalid causing tx revert * Example (consider maxConfToPriceRatio = 3%) * Valid price: * Price: 3000 * Confidence interval: 15 * confToPriceRatio = 15/3000 = 0.5% * Invalid price: * Price: 3000 * Confidence interval: 120 * confToPriceRatio = 120/3000 = 4% * Staleness Period * Gearbox contracts track the timestamp of last Feed's update\ If the update happened more than Staleness Period seconds ago, feed value should be updated or the contracts will revert * Recommended value for Pull feeds: 240s = 4min Right after a new Pyth feed is deployed it's required to send 0.000001 ETH to its address. Without it won't function and can't be added to Price Feed Store.
External feeds **Click New Feed and select External type** ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/03-setup-details.png) ***Dashboards of external providers:*** * *Redstone:* [***https://app.redstone.finance/app/feeds/***](https://app.redstone.finance/app/feeds/) * *Chainlink:* [***https://docs.chain.link/data-feeds/price-feeds/addresses?page=1\&testnetPage=1***](https://docs.chain.link/data-feeds/price-feeds/addresses?page=1\&testnetPage=1) * *EO:* [***https://docs.eo.app/docs/eprice/feeds-addresses/price-feed-addresses***](https://docs.eo.app/docs/eprice/feeds-addresses/price-feed-addresses) * *Some* *protocols may provide custom feeds compatible with AggregatorV3Interface* * [*Resolv*](https://docs.resolv.xyz/litepaper/for-developers/smart-contracts/price-oracles) * [*Midas*](https://docs.midas.app/defi-integration/price-oracle) ### External feed parameters * Name: * Specify token Symbol and Provider name * Examples: * USDC (Chainlink) * hemiBTC (EO) * ETH (Redstone Push) * mTBILL (Midas NAV) * priceFeedAddress * Address of deployed feed * Staleness Period (in seconds) * Gearbox contracts track the timestamp of last Feed's update\ If the update happened more than Staleness Period seconds ago contracts will revert\ \ \&#xNAN;***Motivation**: If the feed with heartbeat of 24 hours wasn't updated in the last 30 hours, smth bad happened with the oracle providers and protocol operations are blocked waiting for Curator to interfere* * Recommended value: * Heartbeat + 15 minutes for slower chains (Ethereum) * 87 300s = 24h + 15min * Heartbeat + 2 minutes for faster chains * 86 520s = 24h + 2min
ERC4626 exchange rate *This contract fetches mint/redeem rate from specified erc4626 vault and multiplies it by the underlying feed output to return the vault shares' USD price.* **Click New Feed and select ERC4626 type** ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/04-config-parameters.png) ### ERC4626 exchange-rate parameters * Name: * Specify token Symbol and underlying feed price Provider name * Example: * Name: sDAI (Chainlink)\ Will mean that this feed takes ERC4626 sDAI/DAI exchange rate directly from sDAI contract + DAI/USD price from Chainlink * Vault: * Address of ERC4626 vault to fetch mint/redeem rate from. * underlyingPriceFeed: * Select existing price feed * Example: * If the specified vault it sUSDe, then underlying price feed should return USDe/USD price. To understand what asset's feed should be passed as underlying, go to the ERC4626 vault contract and call its ***asset()*** method — you will get the address of the token which is vault's underlying.
Redstone pull **Click New Feed and select Redstone type** ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/05-config-parameters.png) ### Redstone pull parameters * Name: * Specify token Symbol and Price methodology Examples: * Name: ezETH (Market)\ Feed: * Name: ezETH (Fundamental)\ Feed: * Token: * Token address\ Needed for Gearbox contracts to understand what pull feed needs to be updated * descriptionTicker * The same as name\ This parameter is to be removed later * dataServiceId * Most likely should be kept untouched\ Internal variable for non-standard sources of redstone data * dataFeedId * The same as Symbol in Redstone UI ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/06-config-parameters.png) * signersThreshold * Minimum amount of signatures from Redstone nodes to have for the feed's result to be deemed valid. * Redstone currently have maximum of 5 nodes. * The safest option is to set this value to 5 (this was historically used in Gearbox), but sometimes couple of Redstone nodes may stop working for a short periods of time. * Signer 1/2/3/4/5 * Most likely should be kept untouched\ Redstone have fixed list of signers' addresses that rarely (if ever) changes
Kodiak island **Click New Feed and select Kodiak\_island type** ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/07-config-parameters.png) ### Kodiak Island parameters * Name: * Specify token Symbol and sources of Underlying Prices\ Example: * Name: iBERA-iBGT (Pyth; Redstone push) * [Island](https://app.kodiak.finance/#/liquidity/pools/0x24afceb372b755f4953e738d6b38e9e4646d9f57?farm=0x199f156bba61496401dc2a009b5f69eb9a7e6f21\&chain=berachain_mainnet) * Feed0: [Pyth iBERA](https://insights.pyth.network/price-feeds/Crypto.IBERA%2FUSD) * Feed1: [Redstone push iBGT](https://app.redstone.finance/app/feeds/berachain/ibgt/) * kodiakIsland: * Island Address * PriceFeed0 * Select the feed from already added to price token with 0'th index in terms of USD * PriceFeed1 * Select the feed from already added to price token with 1'st index in terms of USD * descriptionTicker * The same as name\ This parameter is to be removed later
Pendle PT **Before any deployment, ensure that pendle market has correct cardinality. It should be no less than twapWindow / blockTime + 1 for a given chain.** To check cardinality, go to LP contract and get \_storage()\[4].\ To update cardinality, call increaseObservationsCardinalityNext of an LP contract. ## Pendle PT via the Chainlink-compatible factory * Factory Addresses: * Plasma: 0xAcD67f36183c8bA6b80Cfa60375510Ce17D0dd26 * Mainnet: 0x9E5129dcC15d39625617DcD7F0F44FB0BB957FFd 1. Deploy PT to SY oracle using createOracle Factory method **Market**: Pendle Market address\ **twapDuration**: twap duration in seconds (1800 recommended)\ **baseOracleType**: 0 (PT to SY price) ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/08-pendle-chainlink-compatible-factory.png) 2. Add deployed pendle feed as external (staleness period = 1) 3. Deploy Composite Gearbox Oracle\ Set Feed 1 to previously deployed PT-to-SY feed\ Set Feed 2 to feed which prices SY to USD SY to USD feed shouldn't be of updatable type (Redstone Pull or Pyth pull) ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/09-pendle-chainlink-compatible-factory.png) 3. Deploy Bounded Gearbox Oracle\ Set underlying feed to previously deployed Composite feed\ Set bound to 1 ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/10-pendle-chainlink-compatible-factory.png) ## Native Gearbox PT feed **Click New Feed and select Pendle PT TWAP type** ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/11-gearbox-pt-feed.png) ### Pendle PT parameters * Name: * Specify token Symbol and source of Underlying Price\ Example: * Name: PT-sUSDE-25SEP2025 (Chainlink) * Underlying feed: sUSDe/USD (Chainlink) * market * Pendle Market address ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/12-config-parameters.png) * UnderlyingPriceFeed * The feed contract is able to fetch price of PT token in terms of SY token from the Pendle Market and then multiplies it by SY price in terms of USD ⇒ underlying feed is an intended method to price SY in terms of USD. * priceToSy * ***Most likely you need to check this box*** (if on the previous step you set underlying price feed to be equal to SY price) * If you don't check this box, you will need to use asset price as underlying price feed. (read more about the difference between Asset and SY [here](https://docs.pendle.finance/Developers/Contracts/StandardizedYield#asset-of-sy--assetinfo-function)) * twapWindow * The window length in seconds for averaging market price * Value of 1800s was usually used for previous deployments ## Bound the PT oracle Set underlying feed to previously deployed PT TWAP feed\ Set bound to 1
Curve Stable **Click New Feed and select Curve\_stable type** ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/13-deploy-bounded-gearbox-oracle.png) ### Curve Stable parameters * **Name** * Specify pool Symbol and sources of Underlying Prices\ Example: * Name: crvUSD-USDC (Chainlink) * [Pool](https://www.curve.finance/dex/ethereum/pools/factory-crvusd-0/deposit/) * Feed0: Chainlink crvUSD * Feed1: Chainlink USDC * **Token** * LP token address ![Figure](https://docs.gearbox.finance/assets/docs/shared/curve-stable-token-input.png) * **Pool** * The address of the pool ![Figure](https://docs.gearbox.finance/assets/docs/shared/curve-stable-pool-input.png) * underlyingPriceFeed 0/1/2/3 * Select a feed from allowed list to price pool's tokens at given indexes * If pool has only 2 tokens in it, specify only underlyingPriceFeed0 & 1
Pendle LP **Before any deployment, ensure that pendle market has correct cardinality. It should be no less than twapWindow / blockTime + 1 for a given chain.** To check cardinality, go to LP contract and get \_storage()\[4].\ To update cardinality, call increaseObservationsCardinalityNext of an LP contract. ## Pendle LP via the Chainlink-compatible factory * Factory Addresses: * Plasma: 0xAcD67f36183c8bA6b80Cfa60375510Ce17D0dd26 * Mainnet: 0x9E5129dcC15d39625617DcD7F0F44FB0BB957FFd 1. Deploy PT to SY oracle using createOracle Factory method **Market**: Pendle Market address\ **twapDuration**: twap duration in seconds (1800 recommended)\ **baseOracleType**: 2 (LP to SY price) ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/08-pendle-chainlink-compatible-factory.png) 2. Add deployed pendle feed as external (staleness period = 1) 3. Deploy Composite Gearbox Oracle\ Set Feed 1 to previously deployed LP-to-SY feed\ Set Feed 2 to feed which prices SY to USD SY to USD feed shouldn't be of updatable type (Redstone Pull or Pyth pull) ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/09-pendle-chainlink-compatible-factory.png) 3. Deploy Bounded Gearbox Oracle\ Set underlying feed to previously deployed Composite feed\ Set bound to 1 ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/10-pendle-chainlink-compatible-factory.png) ## Native Gearbox Pendle LP feed **Click New Feed and select Pendle PT TWAP type** ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/11-gearbox-pt-feed.png) ### Pendle LP parameters * Name: * Specify token Symbol and source of Underlying Price\ Example: * Name: PT-sUSDE-25SEP2025 (Chainlink) * Underlying feed: sUSDe/USD (Chainlink) * market * Pendle Market address ![Figure](https://docs.gearbox.finance/assets/docs/curators/add-required-price-feeds/12-config-parameters.png) * UnderlyingPriceFeed * The feed contract is able to fetch price of PT token in terms of SY token from the Pendle Market and then multiplies it by SY price in terms of USD ⇒ underlying feed is an intended method to price SY in terms of USD. * priceToSy * ***Most likely you need to check this box*** (if on the previous step you set underlying price feed to be equal to SY price) * If you don't check this box, you will need to use asset price as underlying price feed. (read more about the difference between Asset and SY [here](https://docs.pendle.finance/Developers/Contracts/StandardizedYield#asset-of-sy--assetinfo-function)) * twapWindow * The window length in seconds for averaging market price * Value of 1800s was usually used for previous deployments ## Bound the Pendle LP oracle Set underlying feed to previously deployed PT TWAP feed\ Set bound to 1
Balancer V3 LP ## Balancer chainlink-compatible factory Feeds of underlying tokens used for deployment shouldn't be of updatable type (Redstone Pull or Pyth pull) Factory address: * Plasma: 0x86e67E115f96DF37239E0479441303De0de7bc2b * Mainnet: 0x83bf399fa3dc49af8fb5c34031a50c7c93f56129
## Configure Market Source: https://docs.gearbox.finance/curators/configure-market File: content/curators/configure-market.mdx ## Assets ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-market/01-assets.png) 1 ### Add new asset and set Main Feed **Asset:** Collateral token address. Select from PriceFeed Store or [add new if needed.](https://docs.gearbox.finance/curators/add-required-price-feeds) **Price Feed:** Collateral token Main price feed. Select from PriceFeed Store or [add new if needed](https://docs.gearbox.finance/curators/add-required-price-feeds). Main feed is used to for collateral pricing during liquidation checks. 2 ### Set Reserve Feed Select from PriceFeed Store or [add new if needed](https://docs.gearbox.finance/curators/add-required-price-feeds). Used to protect the protocol against manipulations of Main Feeds’ price. See [Dual-oracle pricing](https://docs.gearbox.finance/core/dual-oracle-system) for detailed explanation. Set Reserve Feed equal to Main Feed if you have no other options.\ \&#xNAN;***If reserve price feed is not set, part of the protocol functions (withdrawals, partial liquidations) won't be available.*** 3 ### Quota limit Max amount of debt that can be backed by particular asset in the pool. Measured in amount of underlying asset. Used for calculation of Account Value and quota interest rate.\ see [Docs](https://docs.gearbox.finance/core/liquidation-dynamics#what-is-a-health-factor) for detailed explanation. 4 ### Quota Increase Fee **Rarely used, feel free to omit**\ When user increases Quota (CA-specific max amount of debt that can be backed by particular collateral), charge a fixed % fee on the quota difference: works like a one-time fee charged on swaps by exchanges. Added to account's Debt. Distributed as a DAO & Curator fee on repayment according to the fee split rules. ## Rates ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-market/02-rates.png) 1 ### Collateral-specific Rates Additional rate which is applied on top of IRM-based utilization rate for borrowing against particular collaterals. To modify collateral-specific rates, set the intended rates in front of each collateral and click "Update Rates". See [Collateral-specific rates](https://docs.gearbox.finance/curators/fee-sharing) for detailed explanation. Setting IRM in a way that **borrow rate at target utilization (\~80-85%)** equals **60-70% of expected collateral yield** will allow you to bootstrap utilization by allowing favorable rates.\ Equlibrium rate can then be found by increasing collateral-specific rates. ## IRM ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-market/03-irm.png) 1 ### IRM parameters Rate curve parameters can be changed after the creation of Market by executing transactions generated from "Change Model" action. ## Loss policy Additional logic applied during CA liquidation if it results in creation of Bad Debt.\ Properly set loss policy is especially helpful in cases when secondary market oracle is used as a Main feed. **Risks of using secondary market price as Main price feed** \ \&#xNAN;***Example**:* * Main ezETH feed - Market price ## Borrower Allowlisting Source: https://docs.gearbox.finance/curators/borrower-allowlisting File: content/curators/borrower-allowlisting.mdx Borrower allowlisting lets a curator restrict new Credit Account openings to approved addresses. Gearbox implements this through a **Degen NFT** contract configured on the Credit Facade. The NFT is an implementation detail. At the product level, its balance represents the number of Credit Accounts an address is allowed to open. ## Why use an allowlist Borrowing activity is often concentrated among a small number of high-volume users. A curator may therefore prefer to give selected partners access while preventing unknown addresses from opening new positions. This reduces the market's exposure to unvetted borrowers while preserving a straightforward experience for approved users. It does not change collateral requirements, debt limits, liquidation rules, or any other Credit Account risk controls. The market remains visible to everyone. A borrower without an available account-opening allowance sees that access is required when viewing the strategy details. ## How it works 1. The curator approves a borrower and mints one or more non-transferable allowances to the borrower's wallet. 2. The borrower opens a Credit Account for the same wallet. 3. The Credit Facade burns one allowance before opening the account. 4. The new Credit Account behaves like any other account in the market. One allowance permits one account opening. A curator can mint multiple allowances to the same address when that borrower needs to open multiple accounts. Allowlisting gates **new account openings only**. It does not restrict or revoke control over a Credit Account that has already been opened. ## Revoking access Unused allowances can be burned to prevent an address from opening additional Credit Accounts. Revocation does not close, freeze, or otherwise change accounts the borrower already owns. In the default implementation, the Market Configurator's emergency admin can burn unused allowances. A curator should therefore include allowance revocation in its access-management process rather than treating removal from an offchain partner list as sufficient. ## Default Degen NFT implementation `DefaultDegenNFT` is Gearbox's standard implementation of the `IDegenNFT` interface. It provides a simple curator-managed allowance system without embedding a particular KYC or partner-verification policy. | Property | Default behavior | | --- | --- | | Eligibility | Decided offchain by the curator; the contract only records issued allowances | | Issuance | The designated `minter` calls `mint(to, amount)` | | Consumption | A valid Credit Facade calls `burn(from, 1)` during `openCreditAccount` | | Revocation | The Market Configurator's emergency admin can burn unused allowances | | Transferability | Transfers and approvals revert; allowances cannot be sold or moved to another wallet | | Metadata | The Market Configurator admin controls a shared base URI | The Market Configurator admin selects the `minter`. In a typical partner-access setup, this is an address controlled by the curator or its access-management service. Token IDs are derived from the recipient address and its existing balance. Applications should use `balanceOf(address)` as the number of available account openings rather than relying on individual token IDs. ## Credit Facade behavior A nonzero `degenNFT` address enables allowlisted account opening on a Credit Facade. When `openCreditAccount` is called: * The caller must be the account owner specified by `onBehalfOf`. * The Credit Facade burns one allowance from that address. * The Credit Manager opens the Credit Account. Opening an account for another address is disabled while allowlisting is enabled. This prevents an approved wallet from using its allowance to create an account for an unapproved owner. ## Integration overview To enable borrower allowlisting, a curator: 1. Deploys an `IDegenNFT`-compatible contract. 2. Registers it as a Degen NFT periphery contract in the Market Configurator. 3. Configures the Credit Facade with the registered contract address. 4. Sets and operates the minter responsible for borrower approvals. The zero address disables Degen NFT gating. A nonzero contract must be registered before it can be used by a Credit Facade. ## Custom implementations Curators are not required to use `DefaultDegenNFT`. Any compatible implementation can connect issuance to a different partner, identity, or compliance process. The Credit Facade only depends on the `IDegenNFT` interface and calls `burn(address, amount)` when an account is opened. A custom implementation is responsible for its own eligibility, issuance, revocation, and accounting rules while preserving that integration behavior. ## Configure Adapters Source: https://docs.gearbox.finance/curators/configure-adapters File: content/curators/configure-adapters.mdx ## ## What are adapters? The Credit Account design enables active interaction with the DeFi ecosystem while borrowing — such as swapping tokens, depositing into vaults, claiming rewards, and more. However, allowing arbitrary operations poses security risks. > Adapters — modular contracts that enable secure, controlled interactions with external protocols. ## Why do curators need to configure adapters? Having adapters properly configured in the market is essential for allowing collateral swaps, 1-click leverage and other UX features of Gearbox protocol. > Existing offchain infra (Front End, Liquidator) rely on router for finding paths from/to available collaterals. Router is not part of Gearbox protocol, therefore it’s not present in Bytecode repository. Router is used by Gearbox SDK to provide swap paths and it doesn’t interact with core contracts directly. ## What protocols are already integrated? | Protocol | Supported actions | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | Uniswap, Sushiswap, Oku Trade [V2](https://docs.gearbox.finance/curators/configure-adapters#uniswap-sushiswap-v2), [V3](https://docs.gearbox.finance/curators/configure-adapters#uniswap-sushiswap-pancakeswap-iguanadex-oku-trade-v3) | Swaps | | Pancakeswap, IguanaDEX [V3](https://docs.gearbox.finance/curators/configure-adapters#uniswap-sushiswap-pancakeswap-iguanadex-oku-trade-v3), [StableSwap](https://docs.gearbox.finance/curators/configure-adapters#pancakeswap-iguanadex-stableswap) | Swaps, Stableswap LP deposits | | Balancer [V2](https://docs.gearbox.finance/curators/configure-adapters#balancer-v2), [V3](https://docs.gearbox.finance/curators/configure-adapters#balancer-v3) | Swaps, LP deposits | | Curve [Stableswap, CryptoSwap, Stable NG](https://docs.gearbox.finance/curators/configure-adapters#curve-stableswap-cryptoswap-and-stableng) | Swaps, LP deposits | | [***Pendle***](https://docs.gearbox.finance/curators/configure-adapters#curve-stableswap-cryptoswap-and-stableng) | PT swaps | | [Mellow](https://docs.gearbox.finance/curators/configure-adapters#mellow-erc4626) ERC4626 vaults, DVstETH | Instant deposits, Delayed withdrawals | | Velodrome, Aerodrome V3, Stableswap | Swaps | | Camelot, Thena (Algebra AMM dexes) V3 | Swaps | | ***Napier*** | PT Swaps, LP deposits | | ***Convex*** | Staking LP, claiming rewards | | [***Fluid DEX***](https://docs.gearbox.finance/curators/configure-adapters#fluid-dex) | Swaps | | Camelot, Thena, Quickswap (Algebra AMM) V3 | Swaps | | ***Trader Joe*** | Swaps | | ***Infrared*** | Staking LP, claiming rewards | | ***Sky*** | DAI - USDS conversion, Staking USDS for SKY | | ***Lido*** | stETH - wstETH conversion | | [***ERC4626***](https://docs.gearbox.finance/curators/configure-adapters#erc4626) | Instant deposits and withdrawals (whenever possible) | | [***Kodiak Island***](https://docs.gearbox.finance/curators/configure-adapters#erc4626) | Deposit into Island, Swaps in pool | | Uniswap V4 | Swaps | | InfiniFi | Instant deposits, Delayed withdrawals | All the source code and audit reports of the contracts can be found in [Bytecode Repository](https://permissionless.gearbox.foundation/bytecode). Use search, click on the target contract and then **View Source** or **View Report**. All the Adapters can be found by searching for the ADAPTER domain in Bytecode Repository. [setup example (BNB chain: USD1 pool, USDX collateral)](https://www.notion.so/Adapter-setup-example-BNB-chain-USD1-pool-USDX-collateral-208145c16224807fa1a0d318c01bc1ae?pvs=21) [setup example (Ethereum chain: tBTC pool, uptBTC collateral)](https://www.notion.so/Adapter-setup-example-Ethereum-chain-tBTC-pool-uptBTC-collateral-20e145c1622480c886d8d43dc5e9f5bb?pvs=21) [setup example (Ethereum chain: USDC pool, frxUSD/USDf collateral)](https://gearboxprotocol.notion.site/Adapter-setup-example-Ethereum-chain-USDC-pool-frxUSD-USDf-collateral-24c145c16224809d80d2d171e1128317?source=copy_link)
Uniswap, Sushiswap V2 ## Uniswap V2 router configuration For the router on the chain to support swaps, Uniswap V2 worker should be configured. It requires passing the following addresses: * SwapRouter * **Add UniswapV2 adapter (requires providing router address):** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/01-router-configuration.png) * Uni V2 deployment addresses: * Sushi V2 deployment addresses: > Before allowing pools in adapter, please ensure that tokens from a pair are added as ***Assets to Market*** and as ***Collaterals to Credit Manager***.\ \ \&#xNAN;*e.g. to add WETH/USDC pool both WETH and USDC must be added before.* * **Configure adapter to whitelist pools:** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/02-router-configuration.png) ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/03-router-configuration.png) * Uni V2 * Configuration requires specifying tokens from a pair ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/04-router-configuration.png) * Sushi V2 * Configuration requires specifying tokens from a pair ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/05-router-configuration.png)
Uniswap, Sushiswap, Pancakeswap, IguanaDEX, Oku trade V3 ## Uniswap V3 router configuration For the router on the chain to support swaps, Uniswap V3 worker should be configured. It requires passing the following addresses: * SwapRouter * QuoterV2 * **Add UniswapV3 adapter (requires providing SwapRouter address):** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/06-router-configuration.png) * Uni V3 deployment addresses: * Sushi V3 deployment addresses: * Oku Trade deployment addresses: * PancakeSwap deployment addresses: * IguanaDEX deployment addresses: > Router deployment must have bytecode of Uniswap's [SwapRouter.sol](https://github.com/Uniswap/v3-periphery/blob/v1.0.0/contracts/SwapRouter.sol) contract. Sometimes it has only [SwapRouter02](https://github.com/Uniswap/swap-router-contracts/blob/main/contracts/SwapRouter02.sol) deployment specified.\ \ On some chains that was already solved by deploying required implementation of router (see below).\ If it's not, reach out to Gearbox contributors. * Custom SwapRouter deployments: * Uni V3 * [BNB chain](https://bscscan.com/address/0xe7aC922b9751C7aca3A46D5505F36d5BbB1456b6#code) * Oku Trade * [Etherlink](https://explorer.etherlink.com/address/0x2afB54fcaECd41BE4Ecd05d7bd2e193F2F05B99d?tab=contract) * [Plasma](https://plasmascan.to/address/0x9Ed7DFCDE80838f9FfaF4e7fFCe5CcE4737c3e3b) * [Optimism](https://explorer.optimism.io/address/0xDb7D5A2146533BAE5C08A869Cb7e085d8Bee6e0F?tab=contract) > Before allowing pools in adapter, please ensure that tokens from a pair are added as ***Assets to Market*** and as ***Collaterals to Credit Manager***.\ \ \&#xNAN;*e.g. to add WETH/USDC pool both WETH and USDC must be added before.* * **Configure adapter to whitelist pools:**\ \&#xNAN;*Configuration requires specifying tokens and fee from a pair* ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/07-router-configuration.png) ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/08-router-configuration.png) * Uni V3 ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/09-router-configuration.png) * Sushi V3 ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/10-router-configuration.png) * [PancakeSwap](https://pancakeswap.finance/info/v3/pairs), [IguanaDEX](https://www.iguanadex.com/info/v3?chain=etherlink) ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/11-router-configuration.png)
Velodrome, Aerodrome Concentrated Liquidity (Slipstream) For the router on the chain to support swaps, Uniswap V3 worker should be configured. It requires passing the following addresses: * SwapRouter * Quoter * **Add UniswapV3 adapter (requires providing SwapRouter address):** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/06-router-configuration.png) * Velodrome V3 (Slipstream) multichain deployment addresses: * Aerodrome V3 (Slipstream) * **Configure adapter to whitelist pools:**\ \&#xNAN;*Configuration requires specifying tokens and fee from a pair* ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/07-router-configuration.png) ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/08-router-configuration.png) * Fee is a number specified in UI divided by 10000\ e.g. Concentrated Volatile 100 ⇒ fee = 0.01%\ Concentrated Stable 1 ⇒ fee = 0.0001% ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/15-router-configuration.png)
Curve StableSwap, CryptoSwap and StableNG * **How to understand what's the type of the pool of interest:** 1. Go to the block explorer page of Curve Address provider on a chain of interest:\ 2. Call Address Provider's get\_address method with id = 7 to get address of MetaRegistry\ On Mainnet MetaRegistry is located [here](https://etherscan.io/address/0xF98B45FA17DE75FB1aD0e7aFD971b0ca00e379fC). 3. Call get\_registry\_handlers\_by\_pool of MetaRegistry, passing target pool address as argument. 4. Check non-zero address from step 3. output. It usually has clues in first lines of its code. > Before adding adapter, please ensure that tokens from a pool and pool LP token itself are added as ***Assets to Market*** and as ***Collaterals to Credit Manager***.\ \ \&#xNAN;*e.g. to add 3Pool (USDC/USDT/DAI) adapter both USDC, USDT, DAI and 3Pool token itself must be added before.*\ \ \&#xNAN;*learn how to find pool's token address below.* * ***If the pool is not Stable NG:***\ \&#xNAN;*Select Curve V1 2/3/4 Assets adapter depending on the number of different tokens in target pool:* ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/16-router-configuration.png) * ***If the pool is Stable NG:***\ \&#xNAN;*Select Curve StableNG adapter:* ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/17-router-configuration.png) > If the pool operates with non-erc20 ETH balance, deploy a ETH Gateway first and then pass it as target address.\ See the list of deployed gateways below and reach out to Gearbox team if the needed is not present. * ***Adapter arguments:*** * **Target Address** * The address of the pool ![Figure](https://docs.gearbox.finance/assets/docs/shared/curve-stable-pool-input.png) * **LP token** * The address of the pool's LP token (may be different from pool itself) ![Figure](https://docs.gearbox.finance/assets/docs/shared/curve-stable-token-input.png) * **Base Pool Address** * Applicable only if pool is a metapool.\ Example: [this](https://www.curve.finance/dex/ethereum/pools/factory-v2-251/deposit/) pool has [FRAX/USDC](https://www.curve.finance/dex/ethereum/pools/fraxusdc/deposit/) as its base pool. * **Crypto Swap or PancakeSwap pool** * If Type of Pool is Crypto Swap (a.k.a Twocrypto/ Tricrypto) checkout this box. * ETH Gateway deployments: * Mainnet: * [ETH/stETH pool](https://etherscan.io/address/0xdc24316b9ae028f1497c275eb9192a3ea0f67022) Gateway: 0x0675cb2066bacae2edfd09633d5b62be3c619a35
PancakeSwap/ IguanaDEX StableSwap > Before adding adapter, please ensure that tokens from a pool and pool LP token itself are added as ***Assets to Market*** and as ***Collaterals to Credit Manager***.\ \ \&#xNAN;*e.g. to add USDX/USDT adapter both USDX, USDT and pool's LP token itself must be added before.*\ \ \&#xNAN;*learn how to find pool's token address below.* * **Select Curve V1 2 Assets adapter:** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/16-router-configuration.png) * **Target Address** * The address of the pool ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/21-router-configuration.png) * **LP token** * The address of the pool's LP token (can be retreived by calling token() method of pool contract) ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/22-router-configuration.png) * **Base Pool Address** * Not applicable to PancakeSwap. Leave untouched. * **Crypto Swap or PancakeSwap pool** * Checkout this checkbox.
Pendle ## Pendle router configuration For the router on the chain to support swaps, Pendle worker should be configured. It requires passing the following addresses: * routerStatic ## Pendle adapter configuration * **Add Pendle adapter (requires providing router address):** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/23-adapter-configuration.png) * Pendle deployment addresses: > Before adding pool to adapter, please ensure that pool's input token and PT token are added as ***Assets to Market*** and as ***Collaterals to Credit Manager***.\ \ \&#xNAN;*e.g. to add Pendle pool for PT-sUSDe, both sUSDe and PT-sUSDe must be added before.* * **Configure adapter to whitelist pools:**\ \&#xNAN;*Configuration requires specifying market address and input/output tokens* ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/24-adapter-configuration.png) ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/25-adapter-configuration.png) * ***Market:*** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/26-adapter-configuration.png) ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/27-adapter-configuration.png) ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/28-adapter-configuration.png) ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/29-adapter-configuration.png) * ***Input token:***\ Select a token that is in the "1 SY Equals To" row on the screenshot above ^ * ***Pendle token:***\ Target PT token
Fluid DEX ## Fluid DEX router configuration For the router on the chain to support swaps, Fluid worker should be configured. It requires passing the following addresses: * fluidDexResolver > Before adding pool to adapter, please ensure that pool's tokens are added as ***Assets to Market*** and as ***Collaterals to Credit Manager***.\ \ \&#xNAN;*e.g. to add Fluid DEX for wstUSR/USDT, both wstUSR and USDT must be added.* * **Add Fluid DEX adapter (requires providing DEX address)** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/30-router-configuration.png) > If the pool includes ETH token, ETH Gateway must be deployed first and then be passed as target address to Fluid DEX adapter. * Fluid deployment addresses: > DEX addresses have names in the similar format: **Dex\_wstUSR\_USDT.**\ Search the name based on required tokens above. * ETH Gateway deployments: * Mainnet: * **Dex\_wstETH\_ETH: 0x9f294BF3201533B652aFb6B10c0385972C28a16f** * **ezETH\_ETH: 0xa59fc0102b7c2aee66e237ee15cb56ad58a97b2e** * **rsETH\_ETH: 0xb219cE3Fa907edCb375B7375F3C50d920e244bba** * **weETH\_ETH:** 0x0A226E0efa6FCF26837441d623210A9464349200
ERC4626 ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/31-router-configuration.png) Takes ERC4626 **Vault Address** as parameter. Target vault must be added as Asset to Market and as Collateral to Credit Manager. > Before adding adapter, please ensure that token being underlying asset of a ERC4626 vault is added as ***Assets to Market*** and as ***Collaterals to Credit Manager***.\ \ \&#xNAN;*e.g. to add sDAI ERC4626 adapter DAI itself must be added before.* Operates using deposit, withdraw, mint and redeem functions of ERC4626 standard. Allows performing swaps from the vault’s **asset** token into ERC4626 vault **share** token. > Sometimes tokens look very much like ERC4626 but with overwritten methods, like those implementing timelocked deposits and withdrawals.\ Note that this adapter works with vanilla standard methods only.\ \ e.g. sUSDe can be minted from USDe using ERC4626 deposit interface, but has timelocked withdrawals.
Kodiak Island ## Kodiak Island router configuration For the router on the chain to support swaps, Kodiak Island worker should be configured. It requires passing: * \_kodiakIslandRouter - 0x679a7C63FC83b6A4D9C1F931891d705483d4791F * \_kodiakSwapRouter - 0xEd158C4b336A6FCb5B193A5570e3a571f6cbe690 * \_kodiakQuoter - 0x644C8D6E501f7C994B74F5ceA96abe65d0BA662B Takes Gateway Address as parameter. On Berachain it's 0x8d41361d340515d1cdd8c369ca7b5c79f6b2e9c9. ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/32-router-configuration.png) After adding adapter, click configure to whitelist particular Islands. > Before adding Island to adapter, please ensure that Island's tokens and Island itself are added as ***Assets to Market*** and as ***Collaterals to Credit Manager***.\ \ \&#xNAN;*e.g. to add WBERA/iBERA Island, WBERA, iBERA and Island must be added.* ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/33-router-configuration.png)
Convex-staked Curve LP > Before adding and configuring Convex pool adapters, ensure that **Curve LP token**, **Convex Deposit Token**, **Staked Phantom Token**, **CRV** and **CVX** are added as collaterals to Market and Credit Manager (everything except **Staked Phantom Token** can have zero limit, LT and feed).\ \ \ **Convex Deposit Token** can be found by its symbol. If the Curve LP token has symbol frxUSDUSDf, then Convex deposit token will have symbol cvxfrxUSDUSDf. **Staked Phantom Token** can be found by its symbol. If the Curve LP token has symbol frxUSDUSDf, then Convex deposit token will have symbol stkcvxfrxUSDUSDf. **Add Convex Base Reward Pool adapter.** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/34-router-configuration.png) * ***Base Reward Pool Address:*** * Rewards contract address from Convex pool Info. ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/35-router-configuration.png) * ***Staked phantom token:*** * **Staked Phantom Token** can be found by its symbol. If the Curve LP token has symbol frxUSDUSDf, then Convex deposit token will have symbol stkcvxfrxUSDUSDf. **Add Convex Booster adapter** > If the Credit Manager already includes the Convex Booster adapter, skip it and proceed to the next step (Update Convex booster Pool IDs). > Booster address is single across all chains and is suggested as default option. ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/36-router-configuration.png) **Update Convex booster Pool IDs** > After each new Convex pool is added, Booster pool ids should be updated. ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/37-router-configuration.png) ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/38-router-configuration.png)
Balancer V2 ## Balancer V2 router configuration For the router on the chain to support swaps, Balancer V2 worker should be configured. Configuration requires passing: * BalancerQueries Balancer deployment addresses can be found [here](https://docs-v2.balancer.fi/reference/contracts/deployment-addresses/mainnet.html). ## Balancer V2 adapter configuration * **Add BalancerV2 adapter (requires providing Vault address):** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/39-adapter-configuration.png) * Deployment addresses:\ > Before adding adapter, please ensure that tokens from a pool and pool LP token itself are added as ***Assets to Market*** and as ***Collaterals to Credit Manager***.\ \ \&#xNAN;*e.g. to add WETH/osETH pool to adapter both WETH, osETH and WETH/osETH token itself must be added before.*\ \ \&#xNAN;*learn how to find pool's token address below.* * **Finding Pool LP Token Address:** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/40-adapter-configuration.png) * **Configure adapter to whitelist pools:** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/41-adapter-configuration.png) ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/42-adapter-configuration.png) * Configuration requires specifying PoolID which can be found on Balancer UI ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/43-adapter-configuration.png)
Balancer V3 ## Balancer V3 router configuration For the router on the chain to support swaps, Balancer V3 worker should be configured. Configuration requires passing: * [BalancerV3MultiActionQueries](https://github.com/Van0k/balancer-queries/blob/master/src/BalancerV3MultiActionQueries.sol) (needs to be deployed manually, reach out to contributors for support) Balancer deployment addresses can be found [here](https://docs.balancer.fi/developer-reference/contracts/deployment-addresses/plasma.html#core-contracts). BalancerV3MultiActionQueries deployments: * Plasma * 0x1a9B1bfD35fA3932493b5f4F20Cb16b2B88Cc0C8 * Mainnet * 0x0BA8417d19D87b7b5C9dA8762ba505d61D1bF1E7 * Optimism * 0x1b8a4BA520C7789D7bE7476960B8Cdd42e57d928 * Monad * 0x79840073664F6c7bD384C3452B2C034cDEEFEAe5 ## Balancer V3 adapter configuration * **Add BalancerV3 adapter (requires providing Gateway address):** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/44-adapter-configuration.png) * Gateway deployment addresses: * Ethereum: * v3.10 (outdated) 0x21f55223de449224e8bdf4f59452e072bdf7af57 * **v3.11** — 0x8A57c21234ddc225499843F6A073dd374c952560 * Plasma: * v3.10 (outdated) 0xd5c89297ad23e12d7f0ff24112418dbe9ebeae56 * **v3.11** — 0x55109bA88c396008cfBe9F27Ad97A7e1e4394f6F * Optimism: * **v3.11** — 0x77b2dfc344072fa242f2d03893ccbdbb0ef47b7c * Monad * **v3.11** — 0x9dA18982a33FD0c7051B19F0d7C76F2d5E7e017c > Before adding adapter, please ensure that tokens from a pool are added as ***Assets to Market*** and as ***Collaterals to Credit Manager***.\ \ \&#xNAN;*e.g. to add* waEthLidowstETH*/rstETH pool to adapter both* waEthLidowstETH*, rstETH and* waEthLidowstETH*/rstETH token itself must be added before.*\ \ \&#xNAN;*learn how to find pool's token address below.* > What are *wa*-tokens?\ It's erc4626 vaults representing positions staked in Aave pools.\ To support swaps from wstETH through waEthLidowstETH*/rstETH* boosted Balancer pool, you need to include wa-token as collateral and add erc4626 adapter with wa-token address as vault which will process swaps from wstETH to waEthLidowstETH. * **Finding Pool LP Token Address:** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/45-adapter-configuration.png) * **Configure adapter to whitelist pools:** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/41-adapter-configuration.png) ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/47-adapter-configuration.png) * Configuration requires specifying Pool Address which can be found on Balancer UI ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/45-adapter-configuration.png)
Mellow ERC4626 ## Mellow ERC4626 router configuration For the router on the chain to support swaps, Mellow worker should be configured. Reach out to contributors for support. > Before adding adapter, please ensure that mellow vault (LRT itself) and its Withdrawal Phantom Token are added ***Assets to Market*** and as ***Collaterals to Credit Manager***.\ \ If the phantom token is not present in PFS, ask Gearbox contributors to help you deploy a new one. ### **Add Mellow ERC4626 adapter:** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/49-add-mellow-erc4626-adapter.png) * Vault address * Select a corresponding Mellow vault (LRT itself) that was previously added as collateral. * Phantom Token * A token that tracks user's position in withdrawal queue and allows unstaking LRT right from the Credit Account. ### **Add Mellow claimer adapter:** This adapter allows claiming unstaked tokens after the redemption request was processed. ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/50-add-mellow-claimer-adapter.png) Mellow Claimer is a contract deployed by Mellow. Deployment addresses can be found here: **Configure Mellow Claimer Adapter** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/51-add-mellow-claimer-adapter.png) ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/52-add-mellow-claimer-adapter.png) * Multi vault * Mellow LRT itself * Phantom token * A token that tracks user's position in withdrawal queue and allows unstaking LRT right from the Credit Account.
Midas (direct deposits & redemptions) Midas risks: \- If Midas rejects a withdrawal request, a credit account that has the request rejected will have its phantom token balance locked and non-claimable. This means that de-facto the account has bad debt (that cannot be liquidated) until the situation is resolved manually \- A gateway has a function to manually process a cancelled request by paying an amount of at least pendingTokenOutAmount for the respective credit account (the function can be called by anyone). This will allow the credit account to claim a withdrawal as if it was normally processed \- It's best to forbid the withdrawal phantom token if there is a rejected request to Gearbox CA, since Midas might accidentally refund the withdrawal to the CA itself, leading to double counting. Forbidding the token will prevent the user to borrow and withdraw more against their collateral in this case. > For safety, each curator on each chain must have its own gateway and phantom token for each vault. Gateway addresses: * Plasma * Hyperithm Curator: 0xB375DF6a1D7a1c172e65D4FBDA2d3caa144Bf8e7 Phantom token addresses: * Plasma * Hyperithm Curator: 0x0835e60e9A56734cEE76e3953c3BE0635Fcb71d5
Velodrome, Aerodrome V1 & V2 (Basic volatile and Basic stable) For the router on the chain to support swaps, Velodrome worker should be configured. It requires passing the following addresses: * Router * **Add Velodrome V2 adapter (requires providing Router address):** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/53-add-mellow-claimer-adapter.png) * Velodrome v2 optimism deployment addresses: * **Configure adapter to whitelist pools:**\ \&#xNAN;*Configuration requires specifying tokens and fee from a pair*\ \&#xNAN;*Look for Pool Factory in deployment addresses* ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/54-add-mellow-claimer-adapter.png) * Is Stable?\ Basic stable ⇒ Stable\ Basic volatile ⇒ not Stable
Uniswap V4 ## Uniswap V4 router configuration For the router on the chain to support swaps, Uniswap V3 worker should be configured. It requires passing the following addresses: * [Universal Router](https://github.com/Uniswap/universal-router/blob/dev/contracts/UniversalRouter.sol) * [Quoter](https://github.com/Uniswap/v4-periphery/blob/main/src/lens/V4Quoter.sol) * **Add UniswapV4 adapter (requires providing Gateway address):** ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/55-router-configuration.png) * Uni V4 deployment addresses: * Gateway deployment addresses: * Monad: 0xCC7944C237DC540585935F19Bc9aeA0003BC4224 * Ethereum: 0x3b74c70283b291e875da84d58176a63dac5d1824 > Before allowing pools in adapter, please ensure that tokens from a pair are added as ***Assets to Market*** and as ***Collaterals to Credit Manager***.\ \ \&#xNAN;*e.g. to add WETH/USDC pool both WETH and USDC must be added before.* > To fetch fee, tick spacing and hook list, go to **Position Manager** contract and call ***poolKeys*** method passing first 52 symbols of pool identifier from Uniswap UI as PoolID.\ \ E.g. if uniswap link has 0x9b25899648292dce5f8805823aebd0d025bf2625be3162a2f1199e13d8d300c8, then 0x9b25899648292dce5f8805823aebd0d025bf2625be3162a2f1 should be passed as poolID to Position Manager. \ \ Position Manager addresses on different chains can be found [here](https://docs.uniswap.org/contracts/v4/deployments). ![Figure](https://docs.gearbox.finance/assets/docs/curators/configure-adapters/56-router-configuration.png) * **Configure adapter to whitelist** \ \&#xNAN;*Configuration requires specifying tokens and fee from a pair*
## Configure fee split Source: https://docs.gearbox.finance/curators/configure-fee-split File: content/curators/configure-fee-split.mdx []()