{"id":24370110,"url":"https://github.com/balmy-protocol/earn-periphery","last_synced_at":"2025-08-04T17:41:54.621Z","repository":{"id":270723621,"uuid":"831009222","full_name":"Balmy-protocol/earn-periphery","owner":"Balmy-protocol","description":"Earn, Balmy's yield generation infrastructure","archived":false,"fork":false,"pushed_at":"2025-03-11T19:25:21.000Z","size":3055,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-11T20:25:44.603Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Balmy-protocol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audits/cantina_december_2024.pdf","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-19T13:00:32.000Z","updated_at":"2025-03-03T18:48:22.000Z","dependencies_parsed_at":"2025-01-02T17:34:35.277Z","dependency_job_id":"a8b5d190-90dc-4704-b922-6a11f9bdd4a9","html_url":"https://github.com/Balmy-protocol/earn-periphery","commit_stats":null,"previous_names":["balmy-protocol/earn-periphery"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Balmy-protocol%2Fearn-periphery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Balmy-protocol%2Fearn-periphery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Balmy-protocol%2Fearn-periphery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Balmy-protocol%2Fearn-periphery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Balmy-protocol","download_url":"https://codeload.github.com/Balmy-protocol/earn-periphery/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243203889,"owners_count":20253367,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-19T04:12:39.942Z","updated_at":"2025-03-12T10:41:29.697Z","avatar_url":"https://github.com/Balmy-protocol.png","language":"Solidity","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Earn Periphery\nThis repository handles everything that is not related to the core logic of the Earn protocol, but is still needs to be deployed on every chain.\n\nWe recommend reading the [Earn Core README](https://github.com/balmy-protocol/earn-core) to understand the overall Earn ecosystem.\n\n## Strategies\nThis repository contains the implementation for many different strategies. Now, strategies can behave pretty similar to each other, so we've decided to create \"layers\" that can be reused between strategies. \n\n### Layers\nLayers add different capabilities to Earn strategies. Each layer has a \"base\" definition that determines the interface that all implementations must follow. Then, each layer version can choose how to implement that interface. For example, one version of the \"creation validation\" layer (explained below) could verify that the user signed the terms of service before depositing. Another version could simply allow all users to deposit without any additional verification.\n\nIt's important to mention that we wanted to design layers to be highly composable, which is hard to do in Solidity. So we've decided to make use of abstract functions to define what each layer needs to implement, but also what they need from their underlying layer. By doing so, all layers can be integrated with other ones without having to know the underlying implementation details. We recommend looking into different layer implementations to get a better understanding of this.\n\n#### Connector\nThe connector layer is responsible for connecting to \"farms\". Farms are other projects that generate yield for the strategy, like Aave, Yearn, etc. So, for example, if you wanted to create a strategy that used Aave to generate yield, you would use Aave's implementation for the connector layer. \n\n#### Creation validation\nThe creation validation layer is responsible for validating the creation of a new position for the strategy. For example, if the strategy required the user to sign terms of service before depositing, it would be validated here.\n\n#### Guardian\nGuardians are one of the most important differentiator for Earn strategies. Guardians are in charge of protecting the strategy's funds from malicious actors. They have the ability to withdraw funds from an underlying farm back into the strategy so, in the case of a hack, the guardian can step in and rescue the funds from being lost. They can also charge a fee for rescued funds.\n\n#### Fees\nThe fees layer is responsible for handling the fees that the strategy will charge their users. These fees could be deposit fees, withdrawal fees, performance fees, etc.\n\n#### Liquidity Mining\nThis layer is responsible for managing the liquidity mining rewards for the strategy. The idea is that external entities can provide extra rewards to incentivize users to deposit into the strategy.\n\n### Delayed Withdrawals\n\nLike we explained before, sometimes strategies can implement a lock up periods for withdrawals. In that case, when a user wants to execute a withdrawal, the strategy will call a \"delayed withdrawal\" adapter to handle the process. It goes without saying that each \"delayed withdrawal\" will be associated to a position so that only accounts with permissions can retrieve the funds later\n\n#### Delayed Withdrawal Adapter\nWhen a delayed withdrawal is started, the strategy will delegate the process to an delayed withdrawal adapter. Each adapter will know how to handle withdrawals with one or more farms. We chose this approach of separating this process from the strategy mainly for two reason:\n\n1. To be able to re-use withdrawal adapters with various different strategies\n2. So that we don't have to worry about migrating delayed withdrawals when a strategy is updated\n\n#### Delayed Withdrawal Manager\n\nWhen a delayed withdrawal is started, the Earn strategy will delegate the withdrawal to a delayed withdraw adapter. That adapter is the one that will start the withdraw, and then register itself to the manager. By doing so, we will be able to track all pending withdrawals for a specific position in one place.\n\nAfter the delay has passed, the user will be able to claim their funds by calling the manager. The manager will then delegate the process to the adapter that originally started the withdrawal, but only after checking that the user has permission to do so.\n\n```mermaid\nflowchart\n    user[User]    \n\n    subgraph earn[Earn]\n      vault(Earn Vault)      \n      strategy(Strategy X)\n      subgraph delayed[Delayed Withdrawals]\n        manager(Delayed Withdrawal\u003c/br\u003eManager)\n        adapter(Adapter Y)\n      end\n    end\n\n    subgraph farms[Farms]\n      farm(Farm Z)\n    end\n\n    user ---\u003e|Starts Withdrawal|vault\n    user ---\u003e|Claims After\u003c/br\u003eDelay|manager    \n    vault ---\u003e|Starts Withdrawal|strategy    \n    strategy ---\u003e|Assigns Delayed\u003c/br\u003eWithdrawal|adapter\n    adapter ---\u003e|Starts and Tracks\u003c/br\u003eDelayed Withdrawals|farm\n    adapter ---\u003e|Registers itself\u003c/br\u003eto position\u003c/br\u003eand strategy|manager\n    manager ---\u003e|Delegates Claims\u003c/br\u003eAfter Delay|adapter\n    manager ---\u003e|Checks Permissions|vault\n\n```\n\n### Deployments\nMost strategies can be reused quite a lot. For example, a strategy that uses Aave as a farm can be used for all Aave tokens, on all chains where Aave is deployed. This means that we could deploy the same strategy quite a few times, but with slightly different configuration.\n\nTo reduce the cost of deploying strategies, we've decided to use [ClonesWithImmutableArgs](https://github.com/wighawag/clones-with-immutable-args), since most configuration we currently support is immutable in their nature.\n\n## Earn Vault Companion\nThe Earn Vault Companion is a contract that is deployed alongside the Earn Vault. It is meant to add new capabilities to the Earn Vault, like:\n- Multicall capabilities\n- Permit2 deposits\n- Swap and deposit\n- Withdraw and swap\n\n## Global Registry\nThe Global Registry is a contract that simply associates a key with a contract address. This is helpful when we want to upgrade a non-core contract without having to update the address on all the strategies that are using it.\n\n## Usage\n\nThis is a list of the most frequently needed commands.\n\n### Build\n\nBuild the contracts:\n\n```sh\n$ forge build\n```\n\n### Clean\n\nDelete the build artifacts and cache directories:\n\n```sh\n$ forge clean\n```\n\n### Compile\n\nCompile the contracts:\n\n```sh\n$ forge build\n```\n\n### Coverage\n\nGet a test coverage report:\n\n```sh\n$ forge coverage\n```\n\n### Format\n\nFormat the contracts:\n\n```sh\n$ forge fmt\n```\n\n### Gas Usage\n\nGet a gas report:\n\n```sh\n$ forge test --gas-report\n```\n\n### Lint\n\nLint the contracts:\n\n```sh\n$ pnpm lint\n```\n\n### Test\n\nRun the tests:\n\n```sh\n$ forge test\n```\n\n## License\n\nThis project is licensed under MIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbalmy-protocol%2Fearn-periphery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbalmy-protocol%2Fearn-periphery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbalmy-protocol%2Fearn-periphery/lists"}