# Introduction Grace is an L2-first cross-margin lending protocol that fairly distributes losses if they occur, making it resilient to oracle manipulation, volatility and exploits. ## The bankrun problem 1. **Bad debt is accrued.** A lending protocol experiences some loss either due to vulnerable code, collateral price volatility or oracle manipulation. 2. **Liquidity is consumed.** The first lenders to withdraw the remaining the liquidity share none of the losses while those unlucky enough to withdraw last lose their entire deposit. 3. **Everyone runs for the exit.** This incentivizes a bank run because even a loss as small as 1% of the protocol’s TVL can cost a depositor 100% of their deposit if they're too late to withdraw. 4. **The protocol becomes unusable.** Any new lenders entering the pool would be adding exit liquidity for existing stuck lenders, allowing them to transfer their previous losses to the new lenders. ## The Graceful solution 1. **Prepare for the worst.** The lending protocol must expect and be able to absorb any amount of loss. Grace achieves this by immediately distributing any loss equally among lenders. 2. **Manage exposure.** Exposure to each collateral in the pool must be limited and predictable. Grace caps total exposure to each collateral in dollar terms. 3. **Compensate risk.** Borrowers should compensate lenders for the collateral risk they're taking. Grace charges borrowers a yearly fee based on their choice of deposited collateral and uses the proceeds to compensate lenders for their risk. 4. **Implement circuit breakers.** Even in the presence of a loss distribution mechanism, the protocol should minimize potential losses. A Pessimistic Price Oracle renders most oracle manipulation attacks unprofitable against Grace. A global daily borrow limit also caps the maximum possible damage by an attack over a single day. # Loss distribution Whenever Grace experiences a loss, the protocol distribute the loss equally among lenders. If any borrower gets liquidated to a point where their remaining collateral value is near 0 while they still owe some debt, the protocol writes off their remaining debt and instantly distributes that loss among the current lenders. This solves the problem of equal loss distribution and removes the incentive of bankruns after the loss because by the time lenders may consider exiting, there’s not any downside left to staying in the pool, there’s only potential upside in the form of future interest. Even if some lenders still try to exit at once, they will no longer increase the loss of the remaining lenders because the loss has already been distributed at that point. Additionally, new lenders are able to enter the pool without sharing the previous losses of existing lenders. The protocol can continue to serve both borrowers and lenders normally after experiencing any amount of loss, giving it a much better chance of eventually recovering the loss using future interest. # Collateral value limits A maximum global deposit limit is set for each collateral in dollar terms. As soon as the limit is reached, whether due to new deposits or a rise in the price of existing deposits, no more deposits can be made. More importantly, when the limit is reached, the oracle price of each unit of collateral is also limited in order to preserve the global collateral value limit based on the deposited number of collateral tokens. This mechanism functions regardless of oracle price, meaning that it is able to control collateral exposure even in the event of oracle price manipulation. Thanks to collateral value limits, cross-margin pools are no longer as strong as their weakest collateral. Exposure to each collateral can be limited without reducing the collateral’s efficiency. When collateral value limits are combined with fair loss distribution, lenders are able to make much more precise risk/reward calculations. They know how much they can expect to lose due to exposure to each collateral vs how much they can expect to earn based on the current interest rate and collateral fees. # Collateral fees In addition to interest payments, borrowers may also pay a variable yearly fee depending on which collaterals they have deposited. This fee is denominated in the each collateral token. This mechanism allows for efficient pricing of collateral risk. For some highly liquid collaterals such as ETH, borrowers may not pay any collateral fees because the collateral risk of ETH is determined to be relatively low. However, for less liquid collaterals or collaterals that are priced by inferior price feeds, borrowers may be charged a higher collateral fee where their collateral balance decreases over time. This fee is charged in exchange for the protocol’s exposure to the user’s collateral regardless of the user’s debt. The user may be charged additional interest based on the amount of tokens that they borrow. All debt interest and collateral fees are accrued to the Reserve contract which backs each GTR token in circulation using its asset reserves. # Pessimistic Price Oracle Grace Pessimistic Price Oracle (PPO) improves upon the previous generation of [FiRM](https://inverse.finance/firm)’s PPO design. This new iteration of PPO renders most flashloan, multi-block and even multi-day collateral inflation and debt deflation attacks ineffective. This allows Grace to dramatically reduce the risk of on-boarding new collateral types and on-chain price feeds that were previously considered too risky. ## Collateral PPO The PPO prevents **the borrowing power** of each collateral from exceeding **the lowest recorded price** of the collateral over the past 2 weeks based on the collateral factor. This removes the incentive of single and multi block attacks because a collateral price inflation attack cannot be profitable regardless of the oracle price originating from the potentially vulnerable price feed. For example, let's say the current ETH collateral 2-week low was $1000. Say ETH has a 50% collateral factor, meaning that you can only borrow 50% of its value. A few days later, ETH oracle price suddenly rises to $3000. Normally you would be able to borrow $1500 (50%). However, this is a problem. Because your collateral's entire value was $1000 only a few days ago, and now you're able to borrow more than its previous value. Therefore, there is a potential for a profitable manipulation here. In this case, the PPO will temporarily reprice ETH down to $2000. Because at $2000 and 50% collateral factor, you are only able to borrow the lowest value of your collateral, which is $1000, but not more. At $2000 ETH, there is no incentivize to manipulate the oracle. At the same time, ETH is still priced much higher than the low ($2000 instead of $1000). {% hint style="info" %} Most times, the PPO will continue to price collateral based on the live oracle price. However, based on the rule outlined above, if the collateral price makes any dangerous swings, the PPO makes sure that these swings are capped to eliminate incentive for manipulation. {% endhint %} ## Debt PPO Grace PPO also adds a similar mechanism for pricing debt tokens, where the highest recorded price over the past 2 weeks is used. This prevents a another class of manipulation attacks where an attacker may try to artificially reduce the price of borrowed tokens in order to increase the amount of tokens that can be borrowed per collateral. Unlike the collateral PPO above, debt PPO does not take collateral factor into consideration. It is a simpler mechanism that simply uses the highest 2-week debt price. # Referral rewards Frontend interfaces, third-party contracts and other integrators of Grace protocol contracts may opt to earn a referral reward equal to 10% of all interest generated by their referred borrowers. The referral reward is autonomously accrued to referrers by the protocol in order to incentivize frontend diversity and decentralization as well as long-term alignment with independent integrators. Borrowers are never charged an extra fee or charged higher interest in order to cover referral rewards. {% hint style="info" %} Grace contracts source code will be open sourced and documented soon. This page will be updated with references to full code documentation and live contract addresses as soon as they become available. {% endhint %} ## Referring borrowers Referral rewards are only accrued when referring users who call the following `borrow` function on any Grace pool contract: ```solidity function borrow(uint256 amount, address referrer) external; ``` where * `amount` is the raw amount of tokens to be borrowed by the user, and * `referrer` is the address of the third-party which will accrue the referral reward Each borrower is only connected to one active referrer per pool contract. If a borrower had already borrowed from the same pool via another referrer, the previous referrer will be replaced by the new referrer address on the next `borrow` call. The new referrer will start accruing referral rewards taking into account the borrower's existing and new debt in the pool. The previous referrer will no longer accrue rewards from this borrower in this pool, but may continue earning rewards for referring the borrower to other pools. This mechanism incentivizes referrers to acquire new borrowers for the protocol but to also maintain the loyalty of referred borrowers over time or risk them switching to other referrers. ## Claiming referrer rewards Referrers may claim all accrued rewards in each pool by calling the following pool function: ```solidity function claimReferralRewards() external; ``` The caller will receive their referrer rewards, if any, in the form of pool receipt tokens. They can later redeem the receipt tokens for the underlying tokens by calling `withdraw` or `redeem` functions on each pool contract. ## Use cases ### Third-party interfaces Frontend interface developers who provide access to Grace protocol contracts can take advantage of referral rewards as a continuous revenue stream. Developers can grow their share of borrower referrals by providing borrowers with improved UI features and experience. ### Leveraged yield protocols Developers may build leveraged yield protocols on top of Grace by depositing user collateral and borrowing tokens to generate yield to the user via external yield opportunities. By taking advantage of referral rewards, developers can generate revenue for their protocol without adding extra costs to the end user. ### Borrow aggregators Borrow aggregator services that allow borrowers to search for the best loan terms across lending protocols can take advantage of referral rewards as a revenue stream when referring borrowers to Grace. ### Wallet developers Mobile, desktop and browser wallet developers can use Grace under the hood to provide loans to their users without charging them extra costs while earning referral rewards from the protocol. # Roadmap ## Phase 1: Public testnet launch * Public user testing on testnet * Heavy protocol changes based on user feedback * Frequent frontend iterations ## Phase 2: Mainnet testrun * Temporary protocol deployment on Base mainnet with low deposit limits * Stress test of risk management features including loss distribution, liquidation, etc. * Quick addition of many collateral types with risky parameters * Direct control of protocol parameters by deployer * Last chance to make contract changes before code freeze * Beginning of audits and security contests ## Phase 3: Guarded launch * Full protocol redeployment after applying audit recommendations * Official GTR token launch * Indirect control of protocol parameters by deployer behind a timelock * Slow raise of deposit limits in order to ensure battletestness * Slow addition of new collateral types with conservative parameters * Bug bounty program ## Phase 4: Governance launch * Deployment of protocol governance, including proposal voting and liquid voting * Beginning of public 3-year liquidity lock-up event * Transfer of protocol contracts' ownership to the on-chain DAO # Supply assets Grace lenders do not earn compounded interest on their supplied assets. Instead, lenders supply assets to earn Grace Tokenized Reserve (GTR) rewards which they can sell or redeem. ## Supply In order to supply assets to Grace, visit the [**Earn page**](https://app.grace.loans/earn) and select an asset to supply. There are no lock-up periods or fees when supplying to, or withdrawing from, the Earn page. Each asset on the Earn page is assigned a different GTR reward rate per month. This reward rate is distributed among all suppliers of the asset. Your personal reward rate is determined based on your supplied amount versus the total amount supplied by all suppliers of the same asset. Large deposits by other suppliers may dilute your share of the displayed GTR reward rate. {% hint style="warning" %} Assets supplied on the Earn page are used as lending liquidity for Grace borrowers. Withdrawal liquidity may be temporarily limited at times of high borrowing demand. Deposits may also incur losses in the event where a loan is written-off as bad debt. {% endhint %} ## Claim GTR rewards Once you've supplied an asset on the Earn page, GTR rewards will immediately start accruing.

The list of supplied pools is only displayed if you have at least one supplied asset on the Earn page.

You must claim GTR rewards of each asset independently when needed. There's no deadline for redeeming GTR rewards. # Using GTR GTR (short for Grace Tokenized Reserve) acts as a direct claim on all protocol reserves. GTR is minted to Grace suppliers in exchange for lending their assets to Grace borrowers. As a GTR holder, you may either: 1. Sell GTR on the secondary market such via an AMM such as Uniswap, or 2. Redeem GTR for a proportional share of protocol reserves ## Sell GTR Before selling GTR, it is crucial to ensure that the market price that you're selling at is equal to or higher than the value of GTR backing. Otherwise, it may be more rational to redeem your GTR tokens directly. You'll find the total backing per 1 GTR under "GTR backing" on the [**GTR page**](https://app.grace.loans/gtr).
At the time of this writing, there are no known venues for trading GTR on the secondary market. It is the responsibility of the user to discover the best available market for trading GTR in terms of price, liquidity and security. ## Redeem GTR Before redeeming GTR, make sure that the price of the GTR token on the secondary is not higher than the backing per GTR. In some cases, the market may price GTR higher than its backing. In this case, it may be more rational to sell GTR on the secondary market. In order to redeem GTR, visit the [GTR page](https://app.grace.loans/gtr) and input the amount of GTR tokens in your wallet that you wish to redeem.
After clicking "Redeem", the GTRs will be burned from your wallet and you will receive each of the displayed assets. The amount of received tokens is proportional to your share of the GTR total supply. For example, if you redeem 10% of total supply of GTRs in circulation, you will receive 10% of the amount of each token in the protocol reserves. # Add/Remove collateral Before borrowing on Grace, you must first deposit at least one collateral. Each collateral asset has a unique yearly collateral fee. This fee is continuously deducted from your deposited collateral amount as soon as you deposit your collateral regardless of your outstanding loans, if any. {% hint style="info" %} The collateral fee is displayed under "APR" next to each collateral. Before depositing collateral, make sure that the fee APR is appropriate for your needs. {% endhint %} You can deposit and withdraw collaterals at the [**Borrow page**](https://app.grace.loans/borrow). Once you deposit your first collateral, the borrow limit progress bar will show your resulting borrow limit. You may then borrow assets up to the new limit.
Once you start borrowing, you may only withdraw your collateral partially without compromising the health of your position. If you wish to fully withdraw your collateral, you must repay all your loans. {% hint style="success" %} Grace never lends your collateral to other borrowers. All collateral is stored within Grace until withdrawal or liquidation. {% endhint %} # Borrow and repay {% hint style="info" %} You must deposit at least one collateral before borrowing. Visit the [Add/Remove collateral page](/borrowers/add-remove-collateral) for instructions on adding collateral. {% endhint %} ## Borrow After depositing collateral, you may borrow one or multiple assets at the [**Borrow page**](https://app.grace.loans/borrow). Interest is continuously added to your debt based on the yearly "APY" displayed next to each borrowable asset. {% hint style="danger" %} Your position will be force-liquidated if you reach 100% of your borrow limit. If your borrow usage comes dangerously close to the limit, consider adding more collateral or repaying some of your loans to avoid force-liquidation. {% endhint %} In addition to your personal borrow limit, all users may be temporarily restricted from borrowing more assets due to insufficient liquidity or if the global daily borrow limit is exceeded. ## Repay You may repay some or all of your loans at the [**Borrow page**](https://app.grace.loans/borrow). If you wish to fully-withdraw your collateral, you must first repay all your loans. When repaying, you may find that your debt amount has grown slightly larger than the originally borrowed amount. This is because accrued interest is also added to your loan. ## Liquidation In the event where your position is force-liquidated, some of your loans will be repaid on your behalf. In this case, your collateral will be reduced by an amount equal to the repaid debt plus a liquidation fee. # Liquidation Borrowers who consume over 100% of their borrow limit are eligible for liquidation. ## How liquidations work Liquidators repay a portion of a borrower's loan in exchange for an equal portion of their collateral plus some incentive. For example, if a borrower uses ETH as collateral and ETH is priced at $2000 and a liquidator repays $1000 of the borrower's debt, they receive 0.5 ETH ($1000) + 10% liquidation incentive from the borrower's collateral. In this case, the liquidator's total reward would be 0.55 ETH ($1100). In this case, the borrower paid a penalty of $100 (0.05 ETH). ## Liquidation rules Liquidators are required to follow 3 rules when liquidating any borrower. Consider a liquidatable position that is backed by different collateral tokens and borrows different tokens. 1. Liquidators may only repay the most borrowed token in the position in dollar terms 2. Liquidators may only receive the most deposited collateral in the position in dollar terms 3. Liquidators may receive a maximum of $1000 in additional liquidation incentive per liquidation Based on rule 1 and 2, a borrower can predict which collaterals or loans will be impacted in case of a future liquidation. For example, if a borrower wishes to protect a specific collateral token from being rewarded to liquidators, they can ensure that said collateral is not the most valuable in dollar terms relative to other collaterals in their position. Based on rule 3, positions of smaller size may be fully liquidated in fewer liquidation transactions than larger positions. This minimizes losses due to liquidations for large positions as well reduces the systemic risk of liquidation cascades. ## Avoiding liquidation In order to avoid liquidation, borrowers are advised to constantly monitor their borrow limit usage. If your usage is nearing 100%, either reduce your limit usage by repaying some loans or increase your limit by adding more collateral. Another strategy is reduce liquidation risk is to diversify your collateral exposure among multiple non-correlated assets in order to prevent full exposure to the price of a single collateral. # Write-off In the unlikely scenario where a borrow position accrues bad debt, anyone can write-off their debt. In this case, all of their remaining debt is forgiven and their remaining collateral is seized. ## Write-off conditions Write-offs are only possible as a last resort for if liquidations fail to repay the full debt of an underwater borrow position. In order for a borrow position to be written-off, the following conditions must both be satisfied: 1. The total value of all collaterals within the position must be lower than the value of outstanding loans based on the oracle price 2. The total value of all collaterals within the position must also be under the $1000 threshold. ## How write-off works If all conditions are satisfied in a borrow position, anyone can trigger a write-off for the position. All remaining loans of the position are permanently removed. The removed loans are registered as a loss and are deducted proportionally from the deposits of pool suppliers. 25% of the remaining collaterals in the position are transferred to the caller of the write-off function as a reward. The remaining 75% of collateral is sent to the Reserve contract where it is added to the backing of GTR tokens. # Smart contracts ## Source code Grace contracts source code can be found on the official Github repository: {% embed url="" %} ## Live Deployments {% tabs %} {% tab title="Ethereum" %}
NameAddress
Core0x164dd1f4174020642967bea521e56fc776742b49
Oracle0x9a4b2f3669cc3e415fce39e32bd57bb5dfd64e16
PoolDeployer0x2c039b25201e85edb94fe844c7002d7f5b19bc10
CollateralDeployer0x0c95bf53cf5b3d05289c4aac86bd8cdafe44647b
RateProvider0x6c2edef87b6e2de7a0b8d7ebd2fe8eb4ef0694c4
Interest RateModel0x1522ad0a3250eb0f64e0acfe090ca40949330cc1
Collateral RateModel0x43e7381b1611fe6a11eae25e91bc70f5eda241d8
BorrowController0x6f25f5a2789fa92ed47e3bde75c211a488dfd9cf
Lens0x88a134ecd0c1dd20b14ab8f49f9f8b60291167bc
GTR0xd921552c27f5e420fc8565cbff0724cb84a7f0f4
Reserve0x296d571864e04e0fbf470fdf037a5ee30fc16a11
VaultFactory0xafb659e53554ceac0d49aafe4524add603caff3f
ClaimHelper0x0ff94681b96d2cdbe5df80380612d58955644615
DOLA Pool0x332ce425328b5d20bf581101bce099d98dc12686
USDC Pool0xf80c614b5f92450d932e4047c6476dfe7a25c850
DAI Pool0xf20f296a3901bfbc66230e5c332ada8a4e482761
USDT Pool0x107c6a6b3196e68a3b1b874e767abf4399694f55
DOLA Vault0x53b3AEFe30C8d3169D076f021bD50Da3Fdbff731
USDC Vault0x13050015783747bd7084fA44Cd297cF4DA7bcC72
DAI Vault0x2228b8603d0EB56E66A365ae9A86fd9E3859aaEe
USDT Vault0x3522C808483c92Db2343B39A448AC37F48057e39
WBTC Collateral0x9B55214aE4fE177a395cd138136e7e66f2268f66
WETH Collateral0x5C4688e5271D4DfAD4e91F13B4804452Aa8d326f
wstETH Collateral0xCDbB333fF4AEb007Bc5566fF609997f8F0Bed7ed
{% endtab %} {% tab title="Base" %}
NameAddress
Core0x1522ad0a3250eb0f64e0acfe090ca40949330cc1
Oracle0x2c039b25201e85edb94fe844c7002d7f5b19bc10
PoolDeployer0x5eb0df003ac658241686b79fc93a4b9be18b0ebf
CollateralDeployer0x5dc3b4d9ca0c5023520876aa3a29deed972d0364
RateProvider0x0c95bf53cf5b3d05289c4aac86bd8cdafe44647b
Interest RateModel0x4ae260196CcF9F251AfdC7b532cC93D11a21fB80
Collateral RateModel0x472c2d61bF28fe869273697667F6E6166DE82d82
BorrowController0x9a4b2f3669cc3e415fce39e32bd57bb5dfd64e16
Lens0x6f25f5a2789fa92ed47e3bde75c211a488dfd9cf
GTR0x88a134ecd0c1dd20b14ab8f49f9f8b60291167bc
Reserve0x164dd1f4174020642967bea521e56fc776742b49
VaultFactory0x383d2111197b74e3363206db8730daaad6ddc0f4
DOLA Pool0x808bcf1170c8427996d199230ae13b3f16f934e6
USDC Pool0xd82d7300e5d3b3db85594e9171af9d58d6628366
DOLA Vault0xa0e9e2bd79c2e44c15c2949c0c3659979ea13456
USDC Vault0xcf96d3a655fecd570a11d758e945bc50631c3640
WETH Collateral0xdb7869ffb1e46dd86746ea7403fa2bb5caf7fa46
AERO Collateral0x5d84bb226a39d67d7b7a01ad0c77223a03735494
cbETH Collateral0x6F6850a67253b606a4569614fC4BA5ef3dF90A39
DEGEN Collateral0xd7D0fCDfa85d5627679d8248fD74A7556877b622
{% endtab %} {% endtabs %} ## Bug reports Users are encouraged to report any potential smart contract bugs to the team. For more information, visit the following page: {% content-ref url="/pages/TReFHEY8Mc6n2hoVG0UM" %} [Security](/technical/security) {% endcontent-ref %} # Oracles Grace relies on the following price feeds to price collaterals and lending assets: {% tabs %} {% tab title="Ethereum" %} ### Lending assets | Asset | Oracle provider | Price feed address | | ----- | --------------- | ------------------ | | DOLA | Fixed to $1 | N/A | | DAI | Fixed to $1 | N/A | | USDC | Fixed to $1 | N/A | | USDT | Fixed to $1 | N/A | ### Collaterals
AssetOracle providerPrice feed address
WBTCChainlink0xF4030086522a5bEEa4988F8cA5B36dbC97BeE88c
WETHChainlink0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419
wstETHChainlink0xecfA54229af789B34555E8354D8b102C641046B7
BALChainlink0xdF2917806E30300537aEB49A7663062F4d1F2b5F
LINKChainlink0x2c1d072e956AFFC0D435Cb7AC38EF18d24d9127c
CVXChainlink0xd962fC30A72A84cE50161031391756Bf2876Af5D
ENSChainlink0x5C00128d4d1c2F4f652C267d7bcdD7aC99C16E16
APEChainlink0xD10aBbC76679a20055E167BB80A24ac851b37056
{% endtab %} {% tab title="Base" %} ### Lending assets | Asset | Oracle provider | Price feed address | | ----- | --------------- | ------------------ | | DOLA | Fixed to $1 | N/A | | USDC | Fixed to $1 | N/A | ### Collaterals
AssetOracle providerPrice feed address
WETHChainlink0x71041dddad3595F9CEd3DcCFBe3D1F4b0a16Bb70
AEROChainlink0x4EC5970fC728C5f65ba413992CD5fF6FD70fcfF0
cbETHChainlink0xd7818272B9e248357d13057AAb0B417aF31E817d
DEGENAPI30x04c52E456Dc35F492AaFab142f53B8f68fb76bCe
{% endtab %} {% endtabs %} # Security ## Audit Grace protocol contracts have been independently audited by Hacken. External audits are not a guarantee of safety. Users are encouraged to remain cautious when depositing funds before the protocol proves itself to be secure over time. {% embed url="" %} ## Bug bounty Bounty hunters are encouraged to report any potential bugs found in Grace protocol contracts. Reports of bugs that may cause loss of user funds are eligible for a bug bounty depending on potential bug severity. We have partnered with Hats Finance in order to manage our bug bounty program. Visit the following link in order to submit bug reports: {% embed url="" %} Grace bug bounty page {% endembed %}