https://github.com/angleprotocol/angle-transmuter
⚗️ Smart contracts for Transmuter, an autonomous and modular price stability module for decentralized stablecoin protocols
https://github.com/angleprotocol/angle-transmuter
Last synced: 18 days ago
JSON representation
⚗️ Smart contracts for Transmuter, an autonomous and modular price stability module for decentralized stablecoin protocols
- Host: GitHub
- URL: https://github.com/angleprotocol/angle-transmuter
- Owner: AngleProtocol
- License: other
- Created: 2023-03-21T11:05:25.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-11-20T15:41:02.000Z (6 months ago)
- Last Synced: 2025-05-06T19:12:15.532Z (18 days ago)
- Language: Solidity
- Homepage:
- Size: 920 KB
- Stars: 31
- Watchers: 3
- Forks: 13
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# 
Angle - Transmuter
[](https://github.com/AngleProtocol/angle-transmuter/actions)
[](https://codecov.io/gh/AngleProtocol/angle-transmuter)
## What is Transmuter?
Transmuter is an autonomous and modular price stability module for decentralized stablecoin protocols.
- 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.
- 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.
Transmuter 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.
---
## Contracts Architecture 🏘️
The 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:
- the [`Swapper`](./contracts/transmuter/facets/Swapper.sol) facet with the logic associated to the mint and burn functionalities of the system
- the [`Redeemer`](./contracts/transmuter/facets/Redeemer.sol) facet for redemptions
- the [`Getters`](./contracts/transmuter/facets/Getters.sol) facet with external getters for UIs and contracts built on top of `Transmuter`
- the [`SettersGovernor`](./contracts/transmuter/facets/SettersGovernor.sol) facet protocols' governance can use to update system parameters.
- the [`SettersGuardian`](./contracts/transmuter/facets/SettersGuardian.sol) facet protocols' guardian can use to update system parameters.
The storage parameters of the system are defined in the [`Storage`](./contracts/transmuter/Storage.sol) file.
The 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.
---
## Documentation 📚
- [Transmuter Whitepaper](https://docs.angle.money/overview/whitepapers)
- [Angle Documentation](https://docs.angle.money)
- [Angle Developers Documentation](https://developers.angle.money)
---
## Security ⛑️
### Trust assumptions of the Transmuter system
The governor role, which will be a multisig or an onchain governance, has all rights, including upgrading contracts, removing funds, changing the code, etc.
The 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.
### Known Issues
- Lack of support for ERC165
- At initialization, fees need to be < 100% for 100% exposure because the first exposures will be ~100%
- If at some point there are 0 funds in the system it’ll break as `amountToNextBreakPoint` will be 0
- 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
- The whitelist function for burns and redemptions are somehow breaking the fairness of the system as whitelisted actors will redeem more value
- 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.
### Audits
The Transmuter and savings smart contracts have been audited by Code4rena, find the audit report [here](https://code4rena.com/reports/2023-06-angle).
---
### Bug Bounty
For 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/).
---
## Deployment Addresses 🚦
- Transmuter for EURA on Ethereum: [0x00253582b2a3FE112feEC532221d9708c64cEFAb](https://etherscan.io/address/0x00253582b2a3FE112feEC532221d9708c64cEFAb)
- Transmuter for USDA on Ethereum: [0x222222fD79264BBE280b4986F6FEfBC3524d0137](https://etherscan.io/address/0x222222fD79264BBE280b4986F6FEfBC3524d0137)
---
## Development 🛠️
This repository is built on [Foundry](https://github.com/foundry-rs/foundry).
### Getting started
#### Install Foundry
If you don't have Foundry:
```bash
curl -L https://foundry.paradigm.xyz | bash
source /root/.zshrc
# or, if you're under bash: source /root/.bashrc
foundryup
```
To install the standard library:
```bash
forge install foundry-rs/forge-std
```
To update libraries:
```bash
forge update
```
#### Install packages
You can install all dependencies by running
```bash
yarn
forge i
```
### Warning
This 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.
#### Create `.env` file
In order to interact with non local networks, you must create an `.env` that has:
- a `MNEMONIC` for each of the chain you
- a network key
- an `ETHERSCAN_API_KEY`
For additional keys, you can check the [`.env.example`](/.env.example) file.
Warning:
- always keep your confidential information safe
- 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
---
### Compilation
Compilation of production contracts will be done using the via-ir pipeline.
However, 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.
```bash
yarn compile # with via-ir but without compiling tests files
yarn compile:dev # without optimizer
```
### Testing
Here are examples of how to run the test suite:
```bash
yarn test
FOUNDRY_PROFILE=dev forge test -vvv --watch # To watch changing files
FOUNDRY_PROFILE=dev forge test -vvv --match-path test/fuzz/Redeemer.test.sol
FOUNDRY_PROFILE=dev forge test -vvv --match-test "testAbc*"
FOUNDRY_PROFILE=dev forge test -vvv --fork-url
```
You can also list tests:
```bash
FOUNDRY_PROFILE=dev forge test --list
FOUNDRY_PROFILE=dev forge test --list --json --match-test "testXXX*"
```
---
### Deploying
There is an example script in the `scripts/foundry` folder. Then you can run:
```bash
yarn deploy --rpc-url
```
---
### Fork
If you first want to test your deployments/scripts in fork mode. You should run:
```bash
source .env
```
Then fork the network of your choice, by adding the associated script in the `package.json`
```bash
yarn fork:
```
Finnaly run your script in fork mode:
```bash
yarn deploy:fork
```
---
### Coverage
We recommend the use of this [vscode extension](ryanluker.vscode-coverage-gutters).
```bash
yarn coverage
```
You'll need to install lcov `brew install lcov` to visualize the coverage report.
---
### Gas report ⛽️
```bash
yarn gas
```
---
### Etherscan Verification ✅
To 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.
To get the dummy implementation, solution is to:
- download the [repo](https://github.com/zdenham/diamond-etherscan/blob/main/README.md) and follow the instructions
- upload the dummy implementation [here](./scripts/generated/DummyDiamondImplementation.sol)
- 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
- go to Etherscan and point the `DiamondProxy` to the `DiamondEtherscanFacet` contract
Every 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.
---
### [Slither](https://github.com/crytic/slither)
```bash
yarn slither
```
---
## Contributing
If you're interested in contributing, please see our [contributions guidelines](./CONTRIBUTING.md).
---
## Questions & Feedback
For any question or feedback you can send an email to [[email protected]](mailto:[email protected]). Don't hesitate to reach out on [Twitter](https://twitter.com/AngleProtocol)🐦 as well.
---
## Licensing
The primary license for this repository is the Business Source License 1.1 (`BUSL-1.1`). See [`LICENSE`](./LICENSE). Minus the following exceptions:
- [Interfaces](contracts/interfaces/) have a General Public License
- [Some libraries](contracts/transmuter/libraries/LibHelpers.sol) have a General Public License
Each of these files states their license type.