{"id":22873970,"url":"https://github.com/angleprotocol/angle-transmuter","last_synced_at":"2025-05-06T19:12:20.417Z","repository":{"id":176634437,"uuid":"616922844","full_name":"AngleProtocol/angle-transmuter","owner":"AngleProtocol","description":"⚗️ Smart contracts for Transmuter, an autonomous and modular price stability module for decentralized stablecoin protocols","archived":false,"fork":false,"pushed_at":"2024-11-20T15:41:02.000Z","size":942,"stargazers_count":31,"open_issues_count":1,"forks_count":13,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-06T19:12:15.532Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AngleProtocol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-21T11:05:25.000Z","updated_at":"2024-11-20T15:41:04.000Z","dependencies_parsed_at":"2024-01-09T15:59:59.952Z","dependency_job_id":"3db86491-967d-42b0-8d42-9c554a8fb21f","html_url":"https://github.com/AngleProtocol/angle-transmuter","commit_stats":null,"previous_names":["angleprotocol/angle-transmuter"],"tags_count":0,"template":false,"template_full_name":"AngleProtocol/boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AngleProtocol%2Fangle-transmuter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AngleProtocol%2Fangle-transmuter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AngleProtocol%2Fangle-transmuter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AngleProtocol%2Fangle-transmuter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AngleProtocol","download_url":"https://codeload.github.com/AngleProtocol/angle-transmuter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252752060,"owners_count":21798723,"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":"2024-12-13T14:32:09.865Z","updated_at":"2025-05-06T19:12:20.397Z","avatar_url":"https://github.com/AngleProtocol.png","language":"Solidity","readme":"# \u003cimg src=\"logo.svg\" alt=\"Transmuter\" height=\"40px\"\u003e Angle - Transmuter\n\n[![Transmuter CI](https://github.com/AngleProtocol/angle-transmuter/actions/workflows/ci.yml/badge.svg)](https://github.com/AngleProtocol/angle-transmuter/actions)\n[![Coverage](https://codecov.io/gh/AngleProtocol/angle-transmuter/branch/main/graph/badge.svg)](https://codecov.io/gh/AngleProtocol/angle-transmuter)\n\n## What is Transmuter?\n\nTransmuter is an autonomous and modular price stability module for decentralized stablecoin protocols.\n\n- It is conceived as a basket of different assets (normally stablecoins) backing a stablecoin and comes with guarantees on the maximum exposure the stablecoin can have to each asset in the basket.\n- A stablecoin issued through the Transmuter system can be minted at oracle value from any of the assets with adaptive fees, and it can be burnt for any of the assets in the backing with variable fees as well. It can also be redeemed at any time against a proportional amount of each asset in the backing.\n\nTransmuter is compatible with other common mechanisms often used to issue stablecoins like collateralized-debt position models. It is notably used as a standalone module within the Angle Protocol for EURA in parallel with the Borrowing module.\n\n---\n\n## Contracts Architecture 🏘️\n\nThe Transmuter system relies on a [diamond proxy pattern](https://eips.ethereum.org/EIPS/eip-2535). There is as such only one main contract (the `Transmuter` contract) which delegates calls to different facets each with their own implementation. The main facets of the system are:\n\n- the [`Swapper`](./contracts/transmuter/facets/Swapper.sol) facet with the logic associated to the mint and burn functionalities of the system\n- the [`Redeemer`](./contracts/transmuter/facets/Redeemer.sol) facet for redemptions\n- the [`Getters`](./contracts/transmuter/facets/Getters.sol) facet with external getters for UIs and contracts built on top of `Transmuter`\n- the [`SettersGovernor`](./contracts/transmuter/facets/SettersGovernor.sol) facet protocols' governance can use to update system parameters.\n- the [`SettersGuardian`](./contracts/transmuter/facets/SettersGuardian.sol) facet protocols' guardian can use to update system parameters.\n\nThe storage parameters of the system are defined in the [`Storage`](./contracts/transmuter/Storage.sol) file.\n\nThe Transmuter system can come with optional [ERC4626](https://eips.ethereum.org/EIPS/eip-4626) [savings contracts](./contracts/savings/) which can be used to distribute a yield to the holders of the stablecoin issued through the Transmuter.\n\n---\n\n## Documentation 📚\n\n- [Transmuter Whitepaper](https://docs.angle.money/overview/whitepapers)\n- [Angle Documentation](https://docs.angle.money)\n- [Angle Developers Documentation](https://developers.angle.money)\n\n---\n\n## Security ⛑️\n\n### Trust assumptions of the Transmuter system\n\nThe governor role, which will be a multisig or an onchain governance, has all rights, including upgrading contracts, removing funds, changing the code, etc.\n\nThe guardian role, which will be a multisig, has the right to: freeze assets, and potentially impact transient funds. The idea is that any malicious behavior of the guardian should be fixable by the governor, and that the guardian shouldn't be able to extract funds from the system.\n\n### Known Issues\n\n- Lack of support for ERC165\n- At initialization, fees need to be \u003c 100% for 100% exposure because the first exposures will be ~100%\n- If at some point there are 0 funds in the system it’ll break as `amountToNextBreakPoint` will be 0\n- In the burn, if there is one asset which is making 99% of the basket, and another one 1%: if the one making 1% depegs, it still impacts the burn for the asset that makes the majority of the funds\n- The whitelist function for burns and redemptions are somehow breaking the fairness of the system as whitelisted actors will redeem more value\n- The `getCollateralRatio` function may overflow and revert if the amount of stablecoins issued is really small (1 billion x smaller) than the value of the collateral in the system.\n\n### Audits\n\nThe Transmuter and savings smart contracts have been audited by Code4rena, find the audit report [here](https://code4rena.com/reports/2023-06-angle).\n\n---\n\n### Bug Bounty\n\nFor contracts deployed for the Angle Protocol, a bug bounty is open on [Immunefi](https://immunefi.com) and [Hats Finance](https://hats.finance). The rewards and scope of the Angle Immunefi are defined [here](https://immunefi.com/bounty/angleprotocol/).\n\n---\n\n## Deployment Addresses 🚦\n\n- Transmuter for EURA on Ethereum: [0x00253582b2a3FE112feEC532221d9708c64cEFAb](https://etherscan.io/address/0x00253582b2a3FE112feEC532221d9708c64cEFAb)\n- Transmuter for USDA on Ethereum: [0x222222fD79264BBE280b4986F6FEfBC3524d0137](https://etherscan.io/address/0x222222fD79264BBE280b4986F6FEfBC3524d0137)\n\n---\n\n## Development 🛠️\n\nThis repository is built on [Foundry](https://github.com/foundry-rs/foundry).\n\n### Getting started\n\n#### Install Foundry\n\nIf you don't have Foundry:\n\n```bash\ncurl -L https://foundry.paradigm.xyz | bash\n\nsource /root/.zshrc\n# or, if you're under bash: source /root/.bashrc\n\nfoundryup\n```\n\nTo install the standard library:\n\n```bash\nforge install foundry-rs/forge-std\n```\n\nTo update libraries:\n\n```bash\nforge update\n```\n\n#### Install packages\n\nYou can install all dependencies by running\n\n```bash\nyarn\nforge i\n```\n\n### Warning\n\nThis repository uses [`ffi`](https://book.getfoundry.sh/cheatcodes/ffi) in its test suite. Beware as a malicious actor forking this repo could add malicious commands using this.\n\n#### Create `.env` file\n\nIn order to interact with non local networks, you must create an `.env` that has:\n\n- a `MNEMONIC` for each of the chain you\n- a network key\n- an `ETHERSCAN_API_KEY`\n\nFor additional keys, you can check the [`.env.example`](/.env.example) file.\n\nWarning:\n\n- always keep your confidential information safe\n- this repository uses [`ffi`](https://book.getfoundry.sh/cheatcodes/ffi) in its test suite. Beware as a malicious actor forking this repo may execute malicious commands on your machine\n\n---\n\n### Compilation\n\nCompilation of production contracts will be done using the via-ir pipeline.\n\nHowever, tests do not compile with via-ir, and to run coverage the optimizer needs to be off. Therefore for development and test purposes you can compile without optimizer.\n\n```bash\nyarn compile # with via-ir but without compiling tests files\nyarn compile:dev # without optimizer\n```\n\n### Testing\n\nHere are examples of how to run the test suite:\n\n```bash\nyarn test\nFOUNDRY_PROFILE=dev forge test -vvv --watch # To watch changing files\nFOUNDRY_PROFILE=dev forge test -vvv --match-path test/fuzz/Redeemer.test.sol\nFOUNDRY_PROFILE=dev forge test -vvv --match-test \"testAbc*\"\nFOUNDRY_PROFILE=dev forge test -vvv --fork-url \u003cRPC_URL\u003e\n```\n\nYou can also list tests:\n\n```bash\nFOUNDRY_PROFILE=dev forge test --list\nFOUNDRY_PROFILE=dev forge test --list --json --match-test \"testXXX*\"\n```\n\n---\n\n### Deploying\n\nThere is an example script in the `scripts/foundry` folder. Then you can run:\n\n```bash\nyarn deploy \u003cFILE_NAME\u003e --rpc-url \u003cNETWORK_NAME\u003e\n```\n\n---\n\n### Fork\n\nIf you first want to test your deployments/scripts in fork mode. You should run:\n\n```bash\nsource .env\n```\n\nThen fork the network of your choice, by adding the associated script in the `package.json`\n\n```bash\nyarn fork:\u003cCHAIN_NAME\u003e\n```\n\nFinnaly run your script in fork mode:\n\n```bash\nyarn deploy:fork \u003cFILE_NAME\u003e\n```\n\n---\n\n### Coverage\n\nWe recommend the use of this [vscode extension](ryanluker.vscode-coverage-gutters).\n\n```bash\nyarn coverage\n```\n\nYou'll need to install lcov `brew install lcov` to visualize the coverage report.\n\n---\n\n### Gas report ⛽️\n\n```bash\nyarn gas\n```\n\n---\n\n### Etherscan Verification ✅\n\nTo facilitate the interactions with the Diamond Proxy contract on Etherscan, one solution introduced [here](https://github.com/zdenham/diamond-etherscan/blob/main/README.md) is to deploy the system with a dummy facet that is in fact a noop mock of the whole diamond.\n\nTo get the dummy implementation, solution is to:\n\n- download the [repo](https://github.com/zdenham/diamond-etherscan/blob/main/README.md) and follow the instructions\n- upload the dummy implementation [here](./scripts/generated/DummyDiamondImplementation.sol)\n- if the address used has ownership on the Transmuter contracts, run [this script](./scripts/gnosis/VerifyProxyEtherscan.s.sol) to deploy the new dummy facet and add it to the whole Transmuter system\n- go to Etherscan and point the `DiamondProxy` to the `DiamondEtherscanFacet` contract\n\nEvery time a facet is updated with a new function or a change in interface, a new dummy implementation should be deployed and governance should call `DiamondEtherscan.setDummyImplementation()` with the newly deployed dummy implementation.\n\n---\n\n### [Slither](https://github.com/crytic/slither)\n\n```bash\nyarn slither\n```\n\n---\n\n## Contributing\n\nIf you're interested in contributing, please see our [contributions guidelines](./CONTRIBUTING.md).\n\n---\n\n## Questions \u0026 Feedback\n\nFor any question or feedback you can send an email to [contact@angle.money](mailto:contact@angle.money). Don't hesitate to reach out on [Twitter](https://twitter.com/AngleProtocol)🐦 as well.\n\n---\n\n## Licensing\n\nThe primary license for this repository is the Business Source License 1.1 (`BUSL-1.1`). See [`LICENSE`](./LICENSE). Minus the following exceptions:\n\n- [Interfaces](contracts/interfaces/) have a General Public License\n- [Some libraries](contracts/transmuter/libraries/LibHelpers.sol) have a General Public License\n\nEach of these files states their license type.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangleprotocol%2Fangle-transmuter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fangleprotocol%2Fangle-transmuter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fangleprotocol%2Fangle-transmuter/lists"}