{"id":24370114,"url":"https://github.com/balmy-protocol/earn-core","last_synced_at":"2025-04-15T19:40:44.453Z","repository":{"id":270886746,"uuid":"689026165","full_name":"Balmy-protocol/earn-core","owner":"Balmy-protocol","description":"Earn, Balmy's yield generation infrastructure","archived":false,"fork":false,"pushed_at":"2025-01-13T18:12:56.000Z","size":2677,"stargazers_count":5,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-29T00:21:59.447Z","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":"2023-09-08T16:09:39.000Z","updated_at":"2025-03-22T13:29:22.000Z","dependencies_parsed_at":"2025-03-12T10:41:36.907Z","dependency_job_id":"5af9c3bb-61a4-41d7-99b2-5a5dbfbf890e","html_url":"https://github.com/Balmy-protocol/earn-core","commit_stats":null,"previous_names":["balmy-protocol/earn-core"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Balmy-protocol%2Fearn-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Balmy-protocol%2Fearn-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Balmy-protocol%2Fearn-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Balmy-protocol%2Fearn-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Balmy-protocol","download_url":"https://codeload.github.com/Balmy-protocol/earn-core/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249140291,"owners_count":21219266,"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:40.408Z","updated_at":"2025-04-15T19:40:44.433Z","avatar_url":"https://github.com/Balmy-protocol.png","language":"Solidity","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Earn\n\nEarn is Balmy's universal adapter for yield generating vaults. [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) does\na pretty good work of defining how yield vaults should look like, but it doesn't cover all cases. For example, some\nvaults have rounds, where the user can't withdraw until the round is over. In other cases, like LSTs, withdrawals can\ntake a few days to be processed. And finally, there are cases where rewards are generated in tokens that are different\nfrom the one deposited. So the idea is to try to define an universal way of generating and collecting this\nyield/rewards.\n\nIn Earn, a user deposits an \"asset\" and immediately starts generating yield in one or more tokens (one of these tokens\ncould also be the same asset they deposited). When a user deposits their funds, they can choose the \"strategy\" they'd\nlike to use to generate this yield. Earn strategies are in charge of taking the asset and start generating yield, so\nthey will be the ones having control over all user funds. It will be up to each user to do their own due diligence and\nselect their preferred strategy, based on their own risk/reward inclinations.\n\nWhen a user first deposit's into Earn, a \"position\" will be created to track their balances over time. Positions are\nrepresented with NFTs, so they can be transferred. There is also a permission system in place that would allow owners to\ngrant specific permissions to other accounts. Positions can also be modified over time. For example, the owner (or\naccounts with explicit permissions) could withdraw funds or deposit more assets into it.\n\n## Definitions\n\n### Vault\n\nEarn's vault is the place where users deposit and withdraw their funds and rewards. Earn has a singleton vault contract,\nwhich will be the one that keeps track of who owns what. It is also the one that implements access control and makes\nsure that users can only access their own funds.\n\n### Position\n\nIn order to use Earn, users will have to create a position. A position simply keeps track of the funds deposited and\nearned by the user, in the context of a specific strategy. Once a position has been created, it can't change the chosen\nstrategy later.\n\nPositions are represented with NFTs, so they can be transferred. There is also a permission system in place that would\nallow owners to grant specific permissions to other accounts. Positions can also be modified over time. For example, the\nowner (or accounts with explicit permissions) could withdraw funds or deposit more assets into it.\n\n### Asset\n\nWhen we talk about an asset, we refer to a token (could be ERC20 or native) that is deposited by the user to start\ngenerating yield\n\n### Reward Token\n\nLike we said before, a position will deposit an asset, and generate yield in one or more tokens. We'll use the term\n\"reward tokens\" to refer to the tokens that are generating yield, but are not the asset.\n\n### Strategies\n\nIn Earn, a strategy will take an asset and generate yield with it. The generated yield could be in the same asset, or in\nother tokens. One strategy could generate yield on multiple tokens at the same time\n\nEach strategy will have its own logic and risks associated with it. They might use leverage or maybe have some custom\nsafety features, the possibilities are endless. It will be up to each user to do their own due diligence and select\ntheir preferred strategy, based on their own risk/reward inclinations\n\nStrategy devs, please refer to [src/interfaces/IEarnStrategy.sol](src/interfaces/IEarnStrategy.sol) to understand\nimportant restrictions to be considered when building your own strategy\n\n#### Strategy Registry\n\nWhen a position is created, users will have to choose a strategy to generate yield with. In reality, they will be\nassociating their funds to a \"strategy id\" that itself references a strategy contract.\n\nIt could happen that the owner of the strategy wants to upgrade their strategy, so that the strategy id points to a\ndifferent contract. When that happens, they will simply have to go to the strategy registry and propose a \"strategy\nupdate\". Then, after a certain delay has passed, the owner will be able to execute the update. As part of the process,\nthe old vault will be told by the registry that it should migrate all funds over to the new strategy.\n\nIt's important to note that even though we have this delayed upgrade mechanism in place, a strategy might simply\nimplement their own upgradeability process that has no delay at all. So please be careful when selecting a strategy for\nyour funds.\n\n### Special Withdrawals\n\nIn some cases a user might want to perform a \"special withdrawal\". For example, if the strategy were to implement a lock\nup period, the user might prefer to withdraw a token that represents their deposit directly and sell it on the market\nfor a small loss, instead of waiting for the strategy to unlock the funds.\n\nIt will be up to each strategy to support one or more of these special withdrawals\n\nPlease refer to [src/types/SpecialWithdrawals.sol](src/types/SpecialWithdrawals.sol) to understand how to execute and\ninterpret these withdrawals correctly\n\n## Architecture Summary\n\nThis is a small summary of how Earn's architecture looks like. Please take into account that when we refer to \"Strategy\nX\", we are talking about one instance of a strategy, but there are many who perform the same job\n\n```mermaid\nflowchart\n    user[User]\n    admin[Balmy Admin]\n    owner[Strategy Owner]\n\n    subgraph earn[Earn]\n      vault(Earn Vault)\n\n      subgraph strategies[Strategies]\n        strategy(Strategy X)\n        registry(Strategy Registry)\n      end\n    end\n\n    user ---\u003e|Deposits/Withdraws|vault\n    admin ---\u003e|Pauses deposits|vault\n    owner ---\u003e|Register/Updates\u003c/br\u003eStrategy|registry\n    owner ---\u003e|Updates Owner|registry\n    owner ---\u003e|Emergency Actions|strategy\n    registry ---\u003e|Informs Migration|strategy\n    vault ---\u003e|Finds Strategy\u003c/br\u003eby Id|registry\n    vault ---\u003e|Deposits/Withdraws|strategy\n\n```\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$ yarn 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-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbalmy-protocol%2Fearn-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbalmy-protocol%2Fearn-core/lists"}