diff --git a/.gitbook/assets/Mento Protocol Architecture-Circuit Breaker (1).png b/.gitbook/assets/Mento Protocol Architecture-Circuit Breaker (1).png new file mode 100644 index 0000000..a503114 Binary files /dev/null and b/.gitbook/assets/Mento Protocol Architecture-Circuit Breaker (1).png differ diff --git a/.gitbook/assets/Mento Protocol Architecture-System Context.drawio.png b/.gitbook/assets/Mento Protocol Architecture-System Context.drawio.png new file mode 100644 index 0000000..fbc9ff8 Binary files /dev/null and b/.gitbook/assets/Mento Protocol Architecture-System Context.drawio.png differ diff --git a/.gitbook/assets/Screenshot 2023-03-07 at 15.39.39.png b/.gitbook/assets/Screenshot 2023-03-07 at 15.39.39.png new file mode 100644 index 0000000..1fd4d1f Binary files /dev/null and b/.gitbook/assets/Screenshot 2023-03-07 at 15.39.39.png differ diff --git a/.gitbook/assets/Screenshot 2023-03-10 at 18.48.56.png b/.gitbook/assets/Screenshot 2023-03-10 at 18.48.56.png new file mode 100644 index 0000000..824aa37 Binary files /dev/null and b/.gitbook/assets/Screenshot 2023-03-10 at 18.48.56.png differ diff --git a/.gitbook/assets/Screenshot 2023-03-10 at 18.49.17.png b/.gitbook/assets/Screenshot 2023-03-10 at 18.49.17.png new file mode 100644 index 0000000..dc14c07 Binary files /dev/null and b/.gitbook/assets/Screenshot 2023-03-10 at 18.49.17.png differ diff --git a/.gitbook/assets/Screenshot 2023-03-16 at 10.48.11 (1).png b/.gitbook/assets/Screenshot 2023-03-16 at 10.48.11 (1).png new file mode 100644 index 0000000..db51601 Binary files /dev/null and b/.gitbook/assets/Screenshot 2023-03-16 at 10.48.11 (1).png differ diff --git a/.gitbook/assets/Screenshot 2023-03-16 at 10.48.11.png b/.gitbook/assets/Screenshot 2023-03-16 at 10.48.11.png new file mode 100644 index 0000000..db51601 Binary files /dev/null and b/.gitbook/assets/Screenshot 2023-03-16 at 10.48.11.png differ diff --git a/.gitbook/assets/Screenshot 2023-03-16 at 10.48.21 (1).png b/.gitbook/assets/Screenshot 2023-03-16 at 10.48.21 (1).png new file mode 100644 index 0000000..cc69b66 Binary files /dev/null and b/.gitbook/assets/Screenshot 2023-03-16 at 10.48.21 (1).png differ diff --git a/.gitbook/assets/Screenshot 2023-03-16 at 10.48.21.png b/.gitbook/assets/Screenshot 2023-03-16 at 10.48.21.png new file mode 100644 index 0000000..cc69b66 Binary files /dev/null and b/.gitbook/assets/Screenshot 2023-03-16 at 10.48.21.png differ diff --git a/.gitbook/assets/Screenshot 2023-03-16 at 10.48.29 (1).png b/.gitbook/assets/Screenshot 2023-03-16 at 10.48.29 (1).png new file mode 100644 index 0000000..05c6c4a Binary files /dev/null and b/.gitbook/assets/Screenshot 2023-03-16 at 10.48.29 (1).png differ diff --git a/.gitbook/assets/Screenshot 2023-03-16 at 10.48.29.png b/.gitbook/assets/Screenshot 2023-03-16 at 10.48.29.png new file mode 100644 index 0000000..05c6c4a Binary files /dev/null and b/.gitbook/assets/Screenshot 2023-03-16 at 10.48.29.png differ diff --git a/.gitbook/assets/Screenshot 2023-03-16 at 10.48.54 (1).png b/.gitbook/assets/Screenshot 2023-03-16 at 10.48.54 (1).png new file mode 100644 index 0000000..9c553dd Binary files /dev/null and b/.gitbook/assets/Screenshot 2023-03-16 at 10.48.54 (1).png differ diff --git a/.gitbook/assets/Screenshot 2023-03-16 at 10.48.54.png b/.gitbook/assets/Screenshot 2023-03-16 at 10.48.54.png new file mode 100644 index 0000000..9c553dd Binary files /dev/null and b/.gitbook/assets/Screenshot 2023-03-16 at 10.48.54.png differ diff --git a/.gitbook/assets/image (1).png b/.gitbook/assets/image (1).png new file mode 100644 index 0000000..bee83c4 Binary files /dev/null and b/.gitbook/assets/image (1).png differ diff --git a/.gitbook/assets/image (10).png b/.gitbook/assets/image (10).png new file mode 100644 index 0000000..7ec3ebe Binary files /dev/null and b/.gitbook/assets/image (10).png differ diff --git a/.gitbook/assets/image (11).png b/.gitbook/assets/image (11).png new file mode 100644 index 0000000..701e8ce Binary files /dev/null and b/.gitbook/assets/image (11).png differ diff --git a/.gitbook/assets/image (12).png b/.gitbook/assets/image (12).png new file mode 100644 index 0000000..b25f6c4 Binary files /dev/null and b/.gitbook/assets/image (12).png differ diff --git a/.gitbook/assets/image (13).png b/.gitbook/assets/image (13).png new file mode 100644 index 0000000..ad735eb Binary files /dev/null and b/.gitbook/assets/image (13).png differ diff --git a/.gitbook/assets/image (14).png b/.gitbook/assets/image (14).png new file mode 100644 index 0000000..276ff78 Binary files /dev/null and b/.gitbook/assets/image (14).png differ diff --git a/.gitbook/assets/image (2).png b/.gitbook/assets/image (2).png new file mode 100644 index 0000000..686f0f1 Binary files /dev/null and b/.gitbook/assets/image (2).png differ diff --git a/.gitbook/assets/image (3).png b/.gitbook/assets/image (3).png new file mode 100644 index 0000000..a41cc85 Binary files /dev/null and b/.gitbook/assets/image (3).png differ diff --git a/.gitbook/assets/image (4).png b/.gitbook/assets/image (4).png new file mode 100644 index 0000000..e03898a Binary files /dev/null and b/.gitbook/assets/image (4).png differ diff --git a/.gitbook/assets/image (5).png b/.gitbook/assets/image (5).png new file mode 100644 index 0000000..6095f58 Binary files /dev/null and b/.gitbook/assets/image (5).png differ diff --git a/.gitbook/assets/image (6).png b/.gitbook/assets/image (6).png new file mode 100644 index 0000000..bddd582 Binary files /dev/null and b/.gitbook/assets/image (6).png differ diff --git a/.gitbook/assets/image (7).png b/.gitbook/assets/image (7).png new file mode 100644 index 0000000..447abfc Binary files /dev/null and b/.gitbook/assets/image (7).png differ diff --git a/.gitbook/assets/image (8).png b/.gitbook/assets/image (8).png new file mode 100644 index 0000000..1027874 Binary files /dev/null and b/.gitbook/assets/image (8).png differ diff --git a/.gitbook/assets/image (9).png b/.gitbook/assets/image (9).png new file mode 100644 index 0000000..f1781a2 Binary files /dev/null and b/.gitbook/assets/image (9).png differ diff --git a/.gitbook/assets/image.png b/.gitbook/assets/image.png new file mode 100644 index 0000000..0287dea Binary files /dev/null and b/.gitbook/assets/image.png differ diff --git a/.gitbook/assets/verifyBytecode example.gif b/.gitbook/assets/verifyBytecode example.gif new file mode 100644 index 0000000..4f23c00 Binary files /dev/null and b/.gitbook/assets/verifyBytecode example.gif differ diff --git a/README.md b/README.md index d1ce4b9..a372780 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,15 @@ -# What is Mento? +--- +description: Welcome to the Mento Protocol documentation! +--- -Mento is a decentralized and transparent protocol that enables the creation of stable value digital assets, such as assets that track the value of fiat currencies (commonly referred to as ‘stablecoins’). The goal of Mento is to support the real-[world adoption of di](#user-content-fn-1)[^1]gital currencies by enabling the creation of stable value assets for users around the world. +# Home -Mento is currently live on the Celo blockchain where it operates the Celo Dollar (cUSD), Celo Euro (cEUR), and the Celo Brazilian Real (cReal). All Mento assets are fully collateralized with a diversified portfolio of exogenous crypto assets. \ +Mento is a decentralized and transparent protocol that enables the creation of stable value digital assets. +Here you can find detailed documentation around the following areas: -[^1]: Bayo was here +* Protocol [overview](mento-protocol/what-why-who-mento.md) and [concepts](protocol-concepts/stability.md). +* Technical references and guides across the Mento stack, including [smart contracts](developers/smart-contracts/), [SDK](developers/mento-sdk/), and [Oracles](developers/oracles/). +* Information about [how](developers/deployments/parameters.md) and [where](developers/deployments/) Mento is deployed. +* Economic research [foundations](protocol-concepts/stability.md) of and [insights](economics/research.md) into the protocol +* How to create and where to exchange Mento assets in the trading guide. diff --git a/SUMMARY.md b/SUMMARY.md index fa7f88d..a303694 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,70 +1,61 @@ # Table of contents -## Introduction +## Mento Protocol -* [What is Mento?](README.md) -* [Why Mento?](introduction/why-mento.md) +* [Home](README.md) +* [What, why, who Mento?](mento-protocol/what-why-who-mento.md) +* [Quick Links](mento-protocol/quick-links.md) -## Users +## User Trading Guide -* [Trading guide](users/trading-guide/README.md) - * [Centralized exchanges](users/trading-guide/centralized-exchanges.md) - * [Decentralized exchanges](users/trading-guide/decentralized-exchanges.md) - * [Mint/burn with Mento](users/trading-guide/mint-burn-with-mento.md) - * [Limit order & max slippage](users/trading-guide/limit-order-and-max-slippage.md) - * [On-ramp providers](users/trading-guide/on-ramp-providers.md) +* [On Celo](user-trading-guide/on-celo.md) +* [From Ethereum](user-trading-guide/from-ethereum.md) +* [Centralized Exchanges](user-trading-guide/centralized-exchanges.md) +* [On-ramp Providers](user-trading-guide/on-ramp-providers.md) -## Developers - -* [Mento Core](developers/mento-core/README.md) - * [Architecture](developers/mento-core/architecture.md) - * [Smart Contracts](developers/mento-core/smart-contracts/README.md) - * [Broker](developers/mento-core/smart-contracts/broker/README.md) - * [TradingLimits](developers/mento-core/smart-contracts/broker/tradinglimits.md) - * [IExchangeProvider](developers/mento-core/smart-contracts/iexchangeprovider/README.md) - * [BiPoolManager](developers/mento-core/smart-contracts/iexchangeprovider/bipoolmanager/README.md) - * [Pool Structs](developers/mento-core/smart-contracts/iexchangeprovider/bipoolmanager/pool-structs.md) - * [ConstantProductPricingModule](developers/mento-core/smart-contracts/iexchangeprovider/bipoolmanager/constantproductpricingmodule.md) - * [ConstantSumPricingModule](developers/mento-core/smart-contracts/iexchangeprovider/bipoolmanager/constantsumpricingmodule.md) - * [SortedOracles](developers/mento-core/smart-contracts/sortedoracles.md) - * [BreakerBox](developers/mento-core/smart-contracts/breakerbox/README.md) - * [IBreakerBox](developers/mento-core/smart-contracts/breakerbox/ibreakerbox.md) - * [IBreaker](developers/mento-core/smart-contracts/breakerbox/ibreaker.md) - * [MedianDeltaBreaker](developers/mento-core/smart-contracts/breakerbox/mediandeltabreaker.md) - * [ValueDeltaBreaker](developers/mento-core/smart-contracts/breakerbox/valuedeltabreaker.md) - * [Reserve](developers/mento-core/smart-contracts/reserve.md) - * [StableToken](developers/mento-core/smart-contracts/stabletoken.md) - * [Design Principles](developers/mento-core/design-principles.md) -* [SDK](developers/sdk/README.md) - * [Getting Exchange Pairs](developers/sdk/getting-exchange-pairs.md) - * [Getting a Quote](developers/sdk/getting-a-quote.md) - * [Initiating a Swap](developers/sdk/initiating-a-swap.md) -* [Running an Oracle](developers/running-an-oracle.md) -* [Deployment Addresses](developers/deployment-addresses/README.md) - * [Verifying deployments](developers/deployment-addresses/verifying-deployments.md) -* [Deployment Parameters](developers/deployment-parameters.md) - -## Protocol - -* [Stability](protocol/stability.md) -* [Reserve](protocol/reserve.md) -* [Oracles](protocol/oracles/README.md) - * [Circuit Breaker](protocol/oracles/circuit-breaker.md) -* [Trading Limits](protocol/trading-limits.md) -* [Risks](protocol/risks.md) +## Protocol Concepts -## Governance +* [Stability](protocol-concepts/stability.md) +* [Reserve](protocol-concepts/reserve.md) +* [Asset exchanges](protocol-concepts/asset-exchanges/README.md) + * [Broker](protocol-concepts/asset-exchanges/broker.md) + * [Trading Limits](protocol-concepts/asset-exchanges/trading-limits.md) + * [Exchange Providers](protocol-concepts/asset-exchanges/exchange-providers.md) + * [BiPoolManager](protocol-concepts/asset-exchanges/bipoolmanager.md) +* [Oracles](protocol-concepts/oracles.md) +* [On-Chain Circuit Breaker](protocol-concepts/on-chain-circuit-breaker.md) +* [Governance](protocol-concepts/governance.md) -* [Governance](governance/governance.md) - -## Audits - -* [Audit reports](audits/audit-reports.md) - -## Resources +## Developers -* [Website](https://www.mento.org/) -* [Mento Reserve](https://reserve.mento.org/) -* [Discord](https://discord.gg/pEeS4YDR) -* [Twitter](https://twitter.com/MentoProtocol) -* [Github](https://github.com/mento-protocol) +* [Repository Overview](developers/repository-overview.md) +* [Smart Contracts](developers/smart-contracts/README.md) + * [Broker](developers/smart-contracts/broker.md) + * [TradingLimits](developers/smart-contracts/tradinglimits.md) + * [BiPoolManager](developers/smart-contracts/bipoolmanager.md) + * [Pricing Modules](developers/smart-contracts/pricing-modules.md) + * [SortedOracles](developers/smart-contracts/sortedoracles.md) + * [BreakerBox](developers/smart-contracts/breakerbox.md) + * [Reserve](developers/smart-contracts/reserve.md) + * [StableToken](developers/smart-contracts/stabletoken.md) + * [Audits](developers/smart-contracts/audits.md) +* [Deployments](developers/deployments/README.md) + * [Addresses](developers/deployments/addresses.md) + * [Verification](developers/deployments/verification.md) + * [Parameters](developers/deployments/parameters.md) +* [Mento SDK](developers/mento-sdk/README.md) + * [Installation](developers/mento-sdk/installation.md) + * [Guides](developers/mento-sdk/guides/README.md) + * [Getting Exchange Pairs](developers/mento-sdk/guides/getting-exchange-pairs.md) + * [Getting a Quote](developers/mento-sdk/guides/getting-a-quote.md) + * [Initiating a Swap](developers/mento-sdk/guides/initiating-a-swap.md) +* [Oracles](developers/oracles/README.md) + * [Oracle Client](developers/oracles/oracle-client/README.md) + * [Price Sources](developers/oracles/oracle-client/price-sources.md) + * [Becoming an Oracle Provider](developers/oracles/becoming-an-oracle-provider.md) + +## Economics + +* [Stability](economics/stability.md) +* [Risks](economics/risks.md) +* [Research](economics/research.md) diff --git a/developers/deployments/README.md b/developers/deployments/README.md new file mode 100644 index 0000000..df7b2d9 --- /dev/null +++ b/developers/deployments/README.md @@ -0,0 +1,3 @@ +# Deployments + +The pages in this section contain information related to the deployment of the Mento protocol, the deployment parameters, the current deployment addresses and how to verify the on-chain bytecode of the deployed contracts. diff --git a/developers/deployments/addresses.md b/developers/deployments/addresses.md new file mode 100644 index 0000000..a32a13c --- /dev/null +++ b/developers/deployments/addresses.md @@ -0,0 +1,61 @@ +# Addresses + +### Externally Owned Accounts (EOAs) and MultiSigs + +| Label | Address | Notes | +| --------------------- | ------------------------------------------ | ----------------------------------------------------- | +| Mento Deployer | 0x56fD3F2bEE130e9867942D0F463a16fBE49B8d81 | Used for contract creation on all environments | +| Mento Reserve Spender | 0x87647780180B8f55980C7D3fFeFe08a9B29e9aE1 | Used with the Partial Reserve for the MU01 deployment | + +## Mento v2.0 + +{% tabs %} +{% tab title="Celo Mainnet" %} + + +
ContractAddressImplementation
Broker0x777A8255cA72412f0d706dc03C9D1987306B4CaD0x1B78f6acD05e7BcB00f74863bfd8a7C264143e37
BiPoolManager0x22d9db95E6Ae61c104A7B6F6C78D7993B94ec9010xa3D754445f8C3a8134F64467826352885558FD65
BreakerBox0x303ED1df62Fa067659B586EbEe8De0EcE824Ab39❌ Non-upgradable
PartialReserve0xea0Cf774eB755fB01FD67fe6B4F93AE4E167afe20xfD9651862Bc1965349E92073152112289393b57d

ConstantSum

PricingModule

0xDebED1F6f6ce9F6e73AA25F95acBFFE2397550Fb❌ Non-upgradable

ConstantProduct

PricingModule

0x0c07126d0CB30E66eF7553Cc7C37143B4f06DddB❌ Non-upgradable
MedianDeltaBreaker0x49349F92D2B17d491e42C8fdB02D19f072F9B5D9❌ Non-upgradable
ValueDeltaBreaker0x4DBC33B3abA78475A5AA4BC7A5B11445d387BF68❌ Non-upgradable
StableToken0x765de816845861e75a25fca122bb6898b8b1282a0x7ae2f384fE14EaD85779f9224558862D6d3E4f28
StableTokenEUR0xd8763cba276a3738e6de85b4b3bf5fded6d6ca730xF6Ce8cf541eCf560f829ef5680683a06D41a6C33
StableTokenBRL0xe8537a3d056da446677b9e9d6c5db704eaab47870x273F1aA3E574BaF38D0C0D668E06B4490c172bC7
SortedOracles0xefb84935239dacdecf7c5ba76d8de40b077b7b330x4B621443c1c749ef5252e8AEE158A52B5eCe304A
+{% endtab %} + +{% tab title="Alfajores" %} +| Contract | Address | Implementation | +| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | +| Broker | [0xD3Dff18E465bCa6241A244144765b4421Ac14D09](https://explorer.celo.org/alfajores/address/0xD3Dff18E465bCa6241A244144765b4421Ac14D09) | [0xA0248A242A1eAca1A0b0513E82246Faa68d3d87C](https://explorer.celo.org/alfajores/address/0xA0248A242A1eAca1A0b0513E82246Faa68d3d87C) | +| BiPoolManager | [0x9B64E8EaBD1a035b148cE970d3319c5C3Ad53EC3](https://explorer.celo.org/alfajores/address/0x9B64E8EaBD1a035b148cE970d3319c5C3Ad53EC3) | [0x203c4dD52957405F8F86C40996e9b5b3bF5a6c95](https://explorer.celo.org/alfajores/address/0x203c4dD52957405F8F86C40996e9b5b3bF5a6c95) | +| BreakerBox | [0xC76BDf0AFb654888728003683cf748A8B1b4f5fD](https://explorer.celo.org/alfajores/address/0xC76BDf0AFb654888728003683cf748A8B1b4f5fD) | ❌ Non-upgradable | +| PartialReserve | [0x603B3f9A1DF5d081f549E8829B2f00bd353523Cd](https://explorer.celo.org/alfajores/address/0x603B3f9A1DF5d081f549E8829B2f00bd353523Cd) | [0x5B4B6ba128c7BA51d63eD7474A7b17492Fb28476](https://explorer.celo.org/alfajores/address/0x5B4B6ba128c7BA51d63eD7474A7b17492Fb28476) | +|

ConstantSum

PricingModule

| [0x474DBf1eDF845410bdaC6aeE97C3CC403651ba2E](https://explorer.celo.org/alfajores/address/0x474DBf1eDF845410bdaC6aeE97C3CC403651ba2E) | ❌ Non-upgradable | +|

ConstantProduct

PricingModule

| [0x99EDce8143FF8AeFA1fBB6C2103B349Add2B9519](https://explorer.celo.org/alfajores/address/0x99EDce8143FF8AeFA1fBB6C2103B349Add2B9519) | ❌ Non-upgradable | +| MedianDeltaBreaker | [0x6B0a2076713fDAef4F9301fe8404a228e3682DE4](https://explorer.celo.org/alfajores/address/0x6B0a2076713fDAef4F9301fe8404a228e3682DE4) | ❌ Non-upgradable | +| ValueDeltaBreaker | [0xfa6fFf746a5E74055e432f3bba26138956AEfbFe](https://explorer.celo.org/alfajores/address/0xfa6fFf746a5E74055e432f3bba26138956AEfbFe) | ❌ Non-upgradable | +| StableToken | [0x874069fa1eb16d44d622f2e0ca25eea172369bc1](https://explorer.celo.org/alfajores/address/0x874069fa1eb16d44d622f2e0ca25eea172369bc1) | [0x555a4D35328462bCadFD9558295F8E0C98FEdea0](https://explorer.celo.org/alfajores/address/0x555a4D35328462bCadFD9558295F8E0C98FEdea0) | +| StableTokenEUR | [0x10c892a6ec43a53e45d0b916b4b7d383b1b78c0f](https://explorer.celo.org/alfajores/address/0x10c892a6ec43a53e45d0b916b4b7d383b1b78c0f) | [0x0B8d1BFdD9F67cdbab70D48C073d39aaf579f69C](https://explorer.celo.org/alfajores/address/0x0B8d1BFdD9F67cdbab70D48C073d39aaf579f69C) | +| StableTokenBRL | [0xe4d517785d091d3c54818832db6094bcc2744545](https://explorer.celo.org/alfajores/address/0xe4d517785d091d3c54818832db6094bcc2744545) | [0x73F93dcc49cB8A239e2032663e9475dd5ef29A08](https://explorer.celo.org/alfajores/address/0x73F93dcc49cB8A239e2032663e9475dd5ef29A08) | +| SortedOracles | [0xfdd8bd58115ffbf04e47411c1d228ecc45e93075](https://explorer.celo.org/alfajores/address/0xfdd8bd58115ffbf04e47411c1d228ecc45e93075) | [0xB07A33093d332f0D2810b36Bdd3c9e7390624F1F](https://explorer.celo.org/alfajores/address/0xB07A33093d332f0D2810b36Bdd3c9e7390624F1F) | +| BridgedUSDC\* | [0x2c4b568dfba1fbdbb4e7dad3f4186b68bce40db3](https://explorer.celo.org/alfajores/address/0x2c4b568dfba1fbdbb4e7dad3f4186b68bce40db3) | ❌ Non-upgradable | + +\*BridgedUSDC is a Mock ERC20 token that we use on testnets as a surrogate for the bridged USDC that will be used in pools Celo Mainnet. +{% endtab %} + +{% tab title="Baklava" %} +
ContractAddressImplementation
Broker0x6723749339e320E1EFcd9f1B0D997ecb455872080xb474472410F72c292280Ad6778978b49B8F7e68c
BiPoolManager0xFF9a3da00F42839CD6D33AD7adf50bCc97B414110xf0e764Da1E61Bd5421692e5d02bdad9f3B09f825
BreakerBox0x5Ea5A5F694F10de979BEeC7b8041E9f931F54bc7❌ Non-upgradable
PartialReserve0x5186f2871b81F057E249c4f4c9400bAbD9689c5d0x1888c9f6d77dDc5517074cb77F024871B9614002

ConstantSum

PricingModule

0x2901da88dd444a3c41AF51696548DEe3524Cf8Dc❌ Non-upgradable

ConstantProduct

PricingModule

0x7586680Dd2e4F977C33cDbd597fa2490e342CbA2❌ Non-upgradable
MedianDeltaBreaker0x286a8137EE9EE6dE8B5e5be334706fA812400994❌ Non-upgradable
ValueDeltaBreaker0xf631F58b1B51E99dF3Ad1CE18f5C42ab41e4A17a❌ Non-upgradable
StableToken0x62492a644a588fd904270bed06ad52b9abfea1ae0xEeFeFD9A550e45a4CB5bF9a00730575FA432324C
StableTokenEUR0xf9ece301247ad2ce21894941830a2470f4e774ca0x17A59968689d209bE30fF52E0C56FF98ace9ee70
StableTokenBRL0x6a0eef2bed4c30dc2cb42fe6c5f01f80f7ef16d10x90bf93550DF89E5625eB90e6ad2B588E8036cD83
SortedOracles0x88a187a876290e9843175027902b9f7f1b092c880x2e229aa95c67baa6c08073f26ABA8E4083e98489
BridgedUSDC*0x4c6B046750F9aBF6F0f3B511217438451bc6Aa02❌ Non-upgradable
+ +\*BridgedUSDC is a Mock ERC20 token that we use on testnets as a surrogate for the bridged USDC that will be used in pools Celo Mainnet. +{% endtab %} +{% endtabs %} + +You can use our [verification flow ](verification.md)to check the addresses listed above. + +## Mento v1.0 + +### Celo Mainnet + +| Contract | Proxy Address | Implementation Address | +| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| [Reserve](https://github.com/mento-protocol/mento-core/blob/develop/contracts/Reserve.sol) | [0x9380fA34Fd9e4Fd14c06305fd7B6199089eD4eb9](https://explorer.celo.org/mainnet/address/0x9380fA34Fd9e4Fd14c06305fd7B6199089eD4eb9) | [0x907F37A0e9B003dF15500C025f7ACb496A726aA0](https://explorer.celo.org/mainnet/address/0x907F37A0e9B003dF15500C025f7ACb496A726aA0) | +| [SortedOracles](https://github.com/mento-protocol/mento-core/blob/develop/contracts/SortedOracles.sol) | [0xefB84935239dAcdecF7c5bA76d8dE40b077B7b33](https://explorer.celo.org/mainnet/address/0xefB84935239dAcdecF7c5bA76d8dE40b077B7b33) | [0xaf5D514bB94023C9Af979821F59A5Eecde0986EF](https://explorer.celo.org/mainnet/address/0xaf5D514bB94023C9Af979821F59A5Eecde0986EF) | +| [Exchange](https://github.com/mento-protocol/mento-core/blob/develop/contracts/Exchange.sol) | [0x67316300f17f063085Ca8bCa4bd3f7a5a3C66275](https://explorer.celo.org/mainnet/address/0x67316300f17f063085Ca8bCa4bd3f7a5a3C66275) | [0x9A470D789BCd392ae4c8f22DB8425b5eF139906C](https://explorer.celo.org/mainnet/address/0x9A470D789BCd392ae4c8f22DB8425b5eF139906C) | +| [ExchangeBRL](https://github.com/mento-protocol/mento-core/blob/develop/contracts/ExchangeBRL.sol) | [0x8f2cf9855C919AFAC8Bd2E7acEc0205ed568a4EA](https://explorer.celo.org/mainnet/address/0x8f2cf9855C919AFAC8Bd2E7acEc0205ed568a4EA) | [0x0d4a42B2fc30AfBF6b6e8f5CE49A659E38A2D112](https://explorer.celo.org/mainnet/address/0x0d4a42B2fc30AfBF6b6e8f5CE49A659E38A2D112) | +| [ExchangeEUR](https://github.com/mento-protocol/mento-core/blob/develop/contracts/ExchangeEUR.sol) | [0xE383394B913d7302c49F794C7d3243c429d53D1d](https://explorer.celo.org/mainnet/address/0xE383394B913d7302c49F794C7d3243c429d53D1d) | [0x32C2dcB7730eD6Fc1Eac0444a668F38Fd7B5dc8D](https://explorer.celo.org/mainnet/address/0x32C2dcB7730eD6Fc1Eac0444a668F38Fd7B5dc8D) | +| [StableToken](https://github.com/mento-protocol/mento-core/blob/develop/contracts/StableToken.sol) | [0x765DE816845861e75A25fCA122bb6898B8B1282a](https://explorer.celo.org/mainnet/address/0x765DE816845861e75A25fCA122bb6898B8B1282a) | [0x18E6BFDc909063F7445E410a5495264619495bCB](https://explorer.celo.org/mainnet/address/0x18E6BFDc909063F7445E410a5495264619495bCB) | +| [StableTokenBRL](https://github.com/mento-protocol/mento-core/blob/develop/contracts/StableTokenBRL.sol) | [0xe8537a3d056DA446677B9E9d6c5dB704EaAb4787](https://explorer.celo.org/mainnet/address/0xe8537a3d056DA446677B9E9d6c5dB704EaAb4787) | [0x5e72978225b5777298B28B7EA543bf0C5FEDDEc8](https://explorer.celo.org/mainnet/address/0x5e72978225b5777298B28B7EA543bf0C5FEDDEc8) | +| [StableTokenEUR](https://github.com/mento-protocol/mento-core/blob/develop/contracts/StableTokenEUR.sol) | [0xD8763CBa276a3738E6DE85b4b3bF5FDed6D6cA73](https://explorer.celo.org/mainnet/address/0xD8763CBa276a3738E6DE85b4b3bF5FDed6D6cA73) | [0x09933e89986FeA776C3Be3556dBF9BA23c240bB3](https://explorer.celo.org/mainnet/address/0x09933e89986FeA776C3Be3556dBF9BA23c240bB3) | diff --git a/developers/deployments/parameters.md b/developers/deployments/parameters.md new file mode 100644 index 0000000..172647e --- /dev/null +++ b/developers/deployments/parameters.md @@ -0,0 +1,5 @@ +# Parameters + +Mento v2.0.0 contracts are configured via [Celo Governance Proposals](https://celo.stake.id/#/). The parametrization and deployment details can be found in the [Mento-Deployment](https://github.com/mento-protocol/mento-deployment) repository and in corresponding governance proposals. This [config library](https://github.com/mento-protocol/mento-deployment/blob/main/script/upgrades/MU01/Config.sol) contains the smart contract and economic parameterization. + +Since governance can change these parameters, what is deployed with this configuration is not necessarily up-to-date. Current parameterization can be accessed in the Celo block explorers with the [deployment addresses](addresses.md). diff --git a/developers/deployments/verification.md b/developers/deployments/verification.md new file mode 100644 index 0000000..bb13b8e --- /dev/null +++ b/developers/deployments/verification.md @@ -0,0 +1,41 @@ +# Verification + +We've built a handy tool to verify that the on-chain bytecode of deployed Mento contracts matches what has been audited. This is a bit technical and requires at least some knowledge of the stack used for smart contract development and how to use the terminal. + +Before you get started make sure you have installed: git, [foundry](https://book.getfoundry.sh/getting-started/installation), node, and yarn. + +1. Clone the [mento-deployments](https://github.com/mento-protocol/mento-deployment) +2. Run `forge install` +3. Run `yarn verify:bytecodes -n -u -c ` + +For the `verifyBytecodes` command, you need to pick three parameters as follows: + +* `network` one of `baklava`, `alfajores` or `celo` +* `upgrade` currently only `MU01` exists which upgrades Mento from v1.0 to v2.0 +* `commit or tag` what version of the source files to check against, this should come from the [audit report](../smart-contracts/audits.md) associated with the upgrade. + +For example, if we want to verify on Celo mainnet we would run this command: + +``` +$ yarn verify:bytecodes -n celo -u MU01 -c v2.0.0 +``` + +
+ +#### Verification script (verifying the verifier) + +In order to trust the results, you also have to trust the verification script. Luckily it's short enough to be able to read comfortably. You can find it here: + +{% embed url="https://github.com/mento-protocol/mento-deployment/blob/main/bin/verifyBytecodes.ts" %} +Link to verification script +{% endembed %} + +The script flow is the following: + +1. Check out the `mento-core` submodule at the supplied commit +2. Clean and recompile all contracts +3. Find deployed contracts by looking at the [broadcast folders](#user-content-fn-1)[^1] related to the upgrade +4. Compare the bytecode found on-chain for a deployed contract with the local compilation results +5. Print a pretty table. + +[^1]: This is where Foundry stores the artifacts of on-chain operations done via scripts. We commit all relevant runs to the repository and use them to reconstruct the state of the system. diff --git a/developers/mento-sdk/README.md b/developers/mento-sdk/README.md new file mode 100644 index 0000000..2047618 --- /dev/null +++ b/developers/mento-sdk/README.md @@ -0,0 +1,5 @@ +# Mento SDK + +A direct way to interact with the Mento Protocol core contracts in Typescript/Javascript environments is through the Mento SDK ([@mento-protocol/mento-sdk](https://www.npmjs.com/package/@mento-protocol/mento-sdk)). The SDK provides easy-to-use abstractions all the way from discovering exchanges and pairs to executing swaps. + +In the following pages, you will learn how to install the SDK as well as guides for basic Broker and Exchange operations. diff --git a/developers/mento-sdk/guides/README.md b/developers/mento-sdk/guides/README.md new file mode 100644 index 0000000..b955b43 --- /dev/null +++ b/developers/mento-sdk/guides/README.md @@ -0,0 +1,2 @@ +# Guides + diff --git a/developers/mento-sdk/guides/getting-a-quote.md b/developers/mento-sdk/guides/getting-a-quote.md new file mode 100644 index 0000000..3d41c3b --- /dev/null +++ b/developers/mento-sdk/guides/getting-a-quote.md @@ -0,0 +1,60 @@ +# Getting a Quote + +After you have already [fetched all tradeable pairs](broken-reference), you are ready to get price quotes directly from the `Broker` contract. In the example below we will do so for the `CELO/cUSD` exchange. + +We start by importing the SDK and instantiating it on the Alfajores Celo testnet: + +```typescript +import { providers, utils } from "ethers"; +import { Mento } from "@mento-protocol/mento-sdk"; + +const provider = new providers.JsonRpcProvider( + "https://alfajores-forno.celo-testnet.org" +); +const mento = await Mento.create(provider); +``` + +In order to get a quote you will need the address of the token you will provide (`tokenIn`) as well as the address of the token you intend to get out (`tokenOut`). In this example we will get a quote for `CELO -> cUSD` using the addresses from the previous step. + +```typescript +const celoTokenAddr = "0xF194afDf50B03e69Bd7D057c1Aa9e10c9954E4C9"; +const cUSDTokenAddr = "0x874069Fa1Eb16D44d622F2e0Ca25eeA172369bC1"; +const tokenUnits = 18; // both CELO and cUSD have 18 decimal places +``` + +We can now get a quote for how much `cUSD` we can expect to receive in exchange for `1 CELO`: + +```typescript +const amountIn = utils.parseUnits("1", tokenUnits); +const quoteAmountOut = await mento.getAmountOut( + celoTokenAddr, + cUSDTokenAddr, + amountIn +); + +console.log( + `~${utils.formatUnits( + quoteAmountOut, + tokenUnits + )} cUSD in exchange for 1 CELO` +); +``` + +Alternatively, you can also get a quote for the amount of tokens that you would need to provide in order to buy an exact amount of another desired token. For example, the amount of `cUSD` needed to buy `1 CELO`: + +```typescript +const amountOut = utils.parseUnits("1", tokenUnits); +const quoteAmountIn = await mento.getAmountIn( + cUSDTokenAddr, + celoTokenAddr, + amountOut +); + +console.log( + `~${utils.formatUnits(quoteAmountIn, tokenUnits)} cUSD needed to buy 1 CELO` +); +``` + +You can find the full runnable code for this section within the [mento-sdk-examples](https://github.com/mento-protocol/mento-sdk-examples) repo: + +{% embed url="https://github.com/mento-protocol/mento-sdk-examples/blob/main/src/quotes.ts" %} diff --git a/developers/mento-sdk/guides/getting-exchange-pairs.md b/developers/mento-sdk/guides/getting-exchange-pairs.md new file mode 100644 index 0000000..c22edcb --- /dev/null +++ b/developers/mento-sdk/guides/getting-exchange-pairs.md @@ -0,0 +1,58 @@ +# Getting Exchange Pairs + +This guide will walk you through an example code snippet for instantiating the SDK and getting all tradeable pairs from exchanges configured in the broker contract within the Alfajores Celo testnet. + +After installing the SDK, we can import it alongside Ethers: + +```typescript +import { Mento } from "@mento-protocol/mento-sdk"; +import { providers } from "ethers"; +``` + +To instantiate the Mento class we will need to pass an Ethers provider or signer object. This example will use a `JsonRpcProvider` connected to [forno](https://docs.celo.org/network/node/forno), a public hosted node service operated by cLabs. + +```typescript +const provider = new providers.JsonRpcProvider( + "https://alfajores-forno.celo-testnet.org" +); +const mento = await Mento.create(provider); +``` + +Now that the Mento class is instantiated, we can fetch all the pairs by calling the `getTradeablePairs` method: + +```typescript +const pairs = await mento.getTradeablePairs(); +console.log(pairs); +``` + +Which will output the list of pairs alongside their token addresses and symbols in an array format: + +```typescript +[ + [ + { + address: '0x874069Fa1Eb16D44d622F2e0Ca25eeA172369bC1', + symbol: 'cUSD' + }, + { + address: '0xF194afDf50B03e69Bd7D057c1Aa9e10c9954E4C9', + symbol: 'CELO' + } + ], + [ + { + address: '0x10c892A6EC43a53E45D0B916B4b7D383B1b78C0F', + symbol: 'cEUR' + }, + { + address: '0xF194afDf50B03e69Bd7D057c1Aa9e10c9954E4C9', + symbol: 'CELO' + } + ], + ... +] +``` + +You can find the full runnable code for this section within the [mento-sdk-examples](https://github.com/mento-protocol/mento-sdk-examples) repo: + +{% embed url="https://github.com/mento-protocol/mento-sdk-examples/blob/main/src/discovery.ts" %} diff --git a/developers/mento-sdk/guides/initiating-a-swap.md b/developers/mento-sdk/guides/initiating-a-swap.md new file mode 100644 index 0000000..81a4948 --- /dev/null +++ b/developers/mento-sdk/guides/initiating-a-swap.md @@ -0,0 +1,73 @@ +# Initiating a Swap + +After you have gotten a [price quote](broken-reference) from the Broker, you can use the sdk to create a swap transaction object which you can then submit to the network. + +So far in the previous examples we have used only a `JsonRpcProvider` for interacting with the contracts. This is fine for read-only contract calls, but in order to generate a signed transaction object you will need to instantiate the SDK with an Ethers signer. + +For state changing operations (e.g. swaps) the SDK returns [TransactionRequest](https://docs.ethers.org/v5/api/providers/types/#providers-TransactionRequest) Ethers objects populated with information from the signer. Submitting the transaction to the network is left to the consumer to give flexibility for apps integrating the SDK for handling the final transaction lifecycle. + +In this example we will use a `Wallet` Ethers signer object which can be instantiated with a private key: + +```typescript +import { Wallet, providers, utils } from "ethers"; + +import { Mento } from "@mento-protocol/mento-sdk"; + +const privateKey = "YOUR_PRIVATE_KEY_HERE"; +const provider = new providers.JsonRpcProvider( + "https://alfajores-forno.celo-testnet.org" +); +const signer = new Wallet(privateKey, provider); +const mento = await Mento.create(signer); +``` + +We will follow along the previous of example of swapping `1 CELO` token into `cUSD`, so we can get a price quote in the same way we previously did: + +```typescript +const celoTokenAddr = "0xF194afDf50B03e69Bd7D057c1Aa9e10c9954E4C9"; +const cUSDTokenAddr = "0x874069Fa1Eb16D44d622F2e0Ca25eeA172369bC1"; +const tokenUnits = 18; // both CELO and cUSD have 18 decimal places + +const amountIn = utils.parseUnits("1", tokenUnits); +const quoteAmountOut = await mento.getAmountOut( + celoTokenAddr, + cUSDTokenAddr, + amountIn +); +``` + +Before we can submit the swap, we will need to approve the `Broker` contract to spend `CELO` tokens on our behalf. The Mento class provides a convenient function for increasing the allowance for a given token by a certain amount: + +```typescript +const allowanceTxObj = await mento.increaseTradingAllowance( + celoTokenAddr, + amountIn +); +const allowanceTx = await signer.sendTransaction(allowanceTxObj); +const allowanceReceipt = await allowanceTx.wait(); +console.log("tx receipt: ", allowanceReceipt); +``` + +{% hint style="info" %} +You can also opt for increasing the broker allowance to a larger amount to not have to execute the above step on every single swap. +{% endhint %} + +After the transaction is included in a block and the allowance is increased we can use a similar process for submitting the swap transaction to the network: + +```typescript +const expectedAmountOut = quoteAmountOut.mul(99).div(100); // allow 1% slippage from quote +const swapTxObj = await mento.swapIn( + celoTokenAddr, + cUSDTokenAddr, + amountIn, + expectedAmountOut +); +const swapTx = await signer.sendTransaction(swapTxObj); +const swapTxReceipt = await swapTx.wait(); +``` + +Similar to the `getAmountIn` price quote method where we get the amount of tokens needed to buy a specific amount of another desired token, the Mento class also exposes a `swapOut` method which takes both the desired `amountOut` as well as a `maxAmountIn` parameter. Try it on your own! + +You can find the full runnable code for this section within the [mento-sdk-examples](https://github.com/mento-protocol/mento-sdk-examples) repo: + +{% embed url="https://github.com/mento-protocol/mento-sdk-examples/blob/main/src/swap.ts" %} diff --git a/developers/mento-sdk/installation.md b/developers/mento-sdk/installation.md new file mode 100644 index 0000000..e107aaf --- /dev/null +++ b/developers/mento-sdk/installation.md @@ -0,0 +1,22 @@ +# Installation + +{% hint style="info" %} +[Ethers v5](https://www.npmjs.com/package/ethers) is required as a peer dependency in order to use the SDK +{% endhint %} + +We recommend installing SDK either through `yarn` or `npm`: + +```bash +yarn add @mento-protocol/mento-sdk +npm i --save @mento-protocol/mento-sdk +``` + +## Using the SDK + +After you've installed the SDK using your favourite package manager, you can go through the following walkthrough guides: + +* [Discovering exchanges and pairs](broken-reference) +* [Getting price quotes](broken-reference) +* [Executing swaps](broken-reference) + +All the codes snippets in the above guides can be found in [mento-sdk-examples](https://github.com/mento-protocol/mento-sdk-examples). We encourage you to clone the repository, and execute the different code snippets as you read through the guides. diff --git a/developers/oracles/README.md b/developers/oracles/README.md new file mode 100644 index 0000000..61b0267 --- /dev/null +++ b/developers/oracles/README.md @@ -0,0 +1,34 @@ +# Oracles + +{% hint style="info" %} +These pages describe the technical details of Oracles on Mento. For an introduction to Oracles and how they work on Mento, please see [oracles.md](../../protocol-concepts/oracles.md "mention") in the [Broken link](broken-reference "mention") section. +{% endhint %} + +Mento Oracles consist of two technical parts: An [on-chain smart contract](../smart-contracts/sortedoracles.md) and [off-chain clients](oracle-client/). In the following pages, you will learn about these two components as well as about the research behind choosing price sources for the oracles to report. + +
+ +### Unique Rate Feed Identifiers + +Each oracle rate, internally called rate feed, is uniquely identified by a `rateFeedID`. It is used when adding oracle rates to the [SortedOracle smart contract](../smart-contracts/sortedoracles.md) by calling the [`addOracle`](https://github.com/mento-protocol/mento-core/blob/develop/contracts/SortedOracles.sol#L152) function in a Celo governance proposal: + +```solidity +addOracle(address token, address oracleAddress) +``` + +For `CELO/cStable` rate feeds, the unique identifier is the address of the stable token. Since this doesn't work for more than one pair including the same stable token, which was not initially planned, a new formula is used to create unique rate feed identifiers for rate feeds other than `CELO/cStable`. + +These identifiers can be derived using the following formula: + +```solidity +address(uint160(uint256(keccak256(${asset0asset1})))) +``` + +For example, `USDCUSD` inserted gives the following formula: + +```solidity +address(uint160(uint256(keccak256("USDCUSD")))) +// == 0xA1A8003936862E7a15092A91898D69fa8bCE290c +``` + +An example can be found in this [Celo Governance Proposal](https://github.com/celo-org/governance/blob/roman/add-usdc-oracles/CGPs/cgp-0071.md#status). diff --git a/developers/oracles/becoming-an-oracle-provider.md b/developers/oracles/becoming-an-oracle-provider.md new file mode 100644 index 0000000..96ec734 --- /dev/null +++ b/developers/oracles/becoming-an-oracle-provider.md @@ -0,0 +1,42 @@ +# Becoming an Oracle Provider + +The Mento community welcomes its members to run their own Oracle Client and contribute to the decentralization and robustness of the protocol. + +### Requirements + +If you are a developer or entity with relevant technical skills, you are welcome to run an Oracle yourself.In order to run an oracle, you can not have any conflicts of interest and have the technical ability to maintain and update oracles as needed. That means some experience with running software in the cloud, IT security, maintaining them, setting up, and responding to alerts. + +### Oracle client code + +The public repository for the oracle client, including technical documentation, can be found[ here](https://github.com/celo-org/celo-oracle) on GitHub. + +### How to get added as an oracle provider + +If you are interested in running an oracle,[ please read this forum post in the Celo forum](https://forum.celo.org/t/decentralized-oracles/3610) for a first overview.Generally, oracle reports on Celo are controlled by Celo governance and the next steps outline the process of how you can be added as a provider. + +1. 1.Express your interest in running an oracle in the[ Celo forum](https://forum.celo.org/) and on the[ #oracle-provider Discord channel](https://discord.com/channels/966739027782955068/1044219395553120276) to initiate the discussion. Here you can get in touch with Mento Labs engineers who can help you in the process, and get first feedback from the Celo community on whether there is support or objection. +2. 2.From that discussion, you can get our technical runbook and deploy an oracle client on the Celo testnet Alfajores. Mento Labs engineers can help with this. +3. 3.The next step would be to deploy oracles on Celo mainnet, ensure they are live and working correctly, and have the addresses ready for a governance proposal. +4. 4.Now it is time to get a security review from the cLabs security team, for this please get in touch on the[ #oracle-provider Discord channel](https://discord.com/channels/966739027782955068/1044219395553120276). +5. 5.Then it is time to prepare and propose a governance proposal. Examples of previous oracle provider additions are here from[ Di Wu](https://celo.stake.id/#/proposal/74) and[ T-Systems.](https://celo.stake.id/#/proposal/77) This includes compensation. +6. 6.If the proposal passes Celo governance, your client addresses will be able to report to the on-chain oracle and your compensation will be initiated. + +### Compensation + +​[The Celo community informally agreed](https://forum.celo.org/t/decentralized-oracles-rewards-proposal/4110/19) on the following compensation, pending a successful governance vote for each added provider.V3 Revised Reward Payment Framework for Operators + +1. 1.Initial Startup Payment - $6,000 +2. 2.​ + * Will cover initial startup costs + * Paid at the time of activating oracle in CELO +3. 3.On-going Monthly Reward - Dependent on number of cStables on the network +4. 4.​ + * Tier 1: Up to 5 cStables - $1500 / month + * Tier 2: Up to 10 cStables - $2000 / month + * Tier 3: 10+ cStables - $2500 / month +5. 5.Initial payment for new cStable launch - $300 +6. 6.​ + * Each new stablecoin launch will have a one-time payment of $300 + * This will cover costs to support a new cStable as we grow. + +Rewards are paid in CELO using a [Celo ReleaseGold](https://docs.celo.org/holder/manage/release-gold#what-is-releasegold) contract. Rewards will be locked for 3 months. This allows time for partners to prove the reliability of their infrastructure. diff --git a/developers/oracles/oracle-client/README.md b/developers/oracles/oracle-client/README.md new file mode 100644 index 0000000..be598fd --- /dev/null +++ b/developers/oracles/oracle-client/README.md @@ -0,0 +1,47 @@ +# Oracle Client + +Mento Oracle Clients are off-chain programs that query and calculate exchange rates from centralized cryptocurrency exchanges and report them to the on-chain [SortedOracle](https://github.com/mento-protocol/mento-core/blob/develop/contracts/SortedOracles.sol) smart contract. The reported exchange rate is calculated as the volume-weighted average mid-price of configured exchange rates that are not excluded by safety conditions. + +As of March 2023, there are ten off-chain oracle clients per exchange rate, of which Mento Labs manages eight. Ongoing decentralization efforts exist[ to add partners, community members, and validators](https://forum.celo.org/t/decentralized-oracles/3610). Two of the ten oracle clients are operated by community members. One by Celo and Mento community member Di Wu (RAinUsTa#0502 on Discord), and one by T-Systems MMS, a subsidiary of Deutsche Telekom. + +{% embed url="https://github.com/celo-org/celo-oracle" %} + +
+ +## Configuration + +Each Oracle client application is configured for one exchange rate and requires a set of configuration parameters. They determine which exchange rates to query, data aggregation, and safeguards. + +The full set of client parameters is explained in more detail here: + +{% embed url="https://github.com/celo-org/celo-oracle/blob/main/README-config.md" %} + +And the deployment config for exchange rate and safe guard parameters can be found in this directory for different exchange rates: + +{% embed url="https://github.com/celo-org/celo-monorepo/tree/master/packages/helm-charts/oracle" %} + +## Safeguards + +#### **Off-chain Client Circuit Breaker** + +If extreme market volatility is detected, the “circuit breaker” will shut down the Oracle. The current implementation assumes that all participating Oracles are operating with a circuit breaker and using the same configuration. The coordinated shutdown of all Oracles prevents the on-chain exchange rate from being updated. Until the circuit breakers are reset, the on-chain exchange rate adjusts dynamically. One-sided trading with the reserve will push the exchange rate towards the current market price, while limiting the effect on the reserve of having a rate that is "wrong". + +#### **Minimum Number of Exchanges** + +The concept here: the more exchanges contributing data, the more accurate the final price. The minimum number of exchanges is a configurable threshold. If the number of exchanges with usable data is below this threshold, the Oracle application does not try to calculate the current price and will not report. + +#### **Maximum Bid-Ask Spread** + +Ticker data contains the current _bid_ and _ask_ on that exchange. The bid refers to the price at which a buyer is willing to buy a specified asset, and the ask refers to the price at which a seller is willing to sell. There is generally a gap, or a "spread", between these, and the actual price is somewhere in between. If the spread is small, the Oracle can be relatively certain of the price. If it is large, it may be less certain. + +Using this safeguard, the Oracle ignores tickers with a spread that is deemed too large. + +#### **Maximum Volume Share per Exchange** + +The current price calculation is volume-weighted. This means that the price on an exchange with high trading volume has a larger effect on the price calculation than an exchange with lower trading volume. + +This configurable threshold allows setting a cap on how much weight any one exchange can have in the calculation. + +#### **Maximum Deviation of Prices** + +If the prices from different sources (i.e. exchanges) deviate too much, it suggests there is too much uncertainty in the current market conditions. When a set threshold is exceeded, the Oracle will avoid reporting a new value until the sources are in closer agreement. diff --git a/developers/oracles/oracle-client/price-sources.md b/developers/oracles/oracle-client/price-sources.md new file mode 100644 index 0000000..20295c8 --- /dev/null +++ b/developers/oracles/oracle-client/price-sources.md @@ -0,0 +1,19 @@ +# Price Sources + +Mento Oracle Clients aggregate data from multiple configured centralized cryptocurrency exchanges. They then calculate a volume-weighted average market price across exchanges. + +For the robustness of the protocol, it is important to choose reliable exchange rates. Researching which rates to use usually starts with getting an overview of what trading pairs for a given exchange rate exist. Time series characteristics like price stability, traded volume, and order book depth can often be analyzed via [coinmarketcap.com](https://coinmarketcap.com/) or [tradingview.com](https://www.tradingview.com/). It is also helpful to check for the stability of these measures over time and check for wash trading, which can usually be approximated by a market maker's opinion. If necessary, more extensive data can be bought from for example [Tardis](https://tardis.dev/). + +

USDCEUR maximum deviation from average analysis example

+ +The oracle client uses a maximum deviation from the average parameter to determine which exchange rates to include in the volume-weighted mean calculation. The goal of researching a set of exchange rates is to have one with a low and stable deviation from its average over time. + +## Adding exchange rates + +New exchange rates or pairs for existing rates can be added with a PR in the celo-monorepo deployment helm charts: + +{% embed url="https://github.com/celo-org/celo-monorepo/tree/master/packages/helm-charts/oracle" %} + +If a new exchange is not yet supported by the oracle client, a new exchange adapter needs to be added like in this [example PR](https://github.com/celo-org/celo-oracle/pull/150). New currency pairs need to be added like in this [example PR](https://github.com/celo-org/celo-oracle/pull/149/files). + +After adding the necessary features and configurations, the client can be tested by adjusting the [developer price sources](https://github.com/celo-org/celo-oracle/blob/main/devPriceSourcesConfig.txt) with the new price sources and running the application locally. A more technical documentation about running the client application locally can be found in the [repository readme](https://github.com/celo-org/celo-oracle) files. diff --git a/developers/repository-overview.md b/developers/repository-overview.md new file mode 100644 index 0000000..4972003 --- /dev/null +++ b/developers/repository-overview.md @@ -0,0 +1,37 @@ +# Repository Overview + +Here you can find an overview of relevant [Mento GitHub repositories](https://github.com/mento-protocol). + +### [Mento Core](https://github.com/mento-protocol/mento-core) + +This repository contains the source code of the core smart contracts for the Mento protocol. The repository is built with foundry which is used for the compilation and testing of the smart contracts. + +### [Mento SDK](https://github.com/mento-protocol/mento-sdk) + +The GitHub repository of the official Mento Protocol SDK for interacting with Multi-Collateral Mento smart contracts on the Celo network. + +### [Mento SDK examples](http://127.0.0.1:5000/s/TTxQdBUOJwGkQLpLLxm8/developers/mento-core/smart-contracts/breakerbox/mediandeltabreaker) + +A set of runnable example code snippets for using the [Mento Protocol SDK](https://www.npmjs.com/package/@mento-protocol/mento-sdk). + +### [Mento App](https://github.com/mento-protocol/mento-web) + +The GitHub repository for the Mento web app. This app lets users make exchanges between Mento collateral and stable assets using the Mento Broker. + +### [Mento Deployments](https://github.com/mento-protocol/mento-deployment) + +This repo contains scripts for deploying & proposing upgrades to the Mento protocol. Deployments for the core contracts are done using [Foundry solidity scripting](https://book.getfoundry.sh/tutorials/solidity-scripting). + + + + + + + + + + + +### + +\ diff --git a/developers/smart-contracts/README.md b/developers/smart-contracts/README.md new file mode 100644 index 0000000..9d3bdde --- /dev/null +++ b/developers/smart-contracts/README.md @@ -0,0 +1,14 @@ +# Smart Contracts + +The Mento protocol consists of a set of smart contracts, which are deployed on the[ Celo blockchain](https://celo.org/). + +Mento Core is the set of smart contracts that allows virtual pools between any mento stable asset and mento collateral asset to be traded under different pricing regimes. These contracts handle all necessary operations that enable everyone to create, exchange, and contribute to the stability of Mento stable currencies. + +The contracts can be found in the mento-protocol/mento-core GitHub repository: + +{% embed url="https://github.com/mento-protocol/mento-core" %} + +Here you will find everything from an overview to a detailed technical reference. + +

Mento Smart Contracts

+ diff --git a/developers/smart-contracts/audits.md b/developers/smart-contracts/audits.md new file mode 100644 index 0000000..0c704c4 --- /dev/null +++ b/developers/smart-contracts/audits.md @@ -0,0 +1,5 @@ +# Audits + + + +
DateLinkAuditorVersion
05/2023Extended previous audit with new v2.findings: https://www.verilog.solutions/audits/mento/Verilogv2.1.0
02/2023https://www.verilog.solutions/audits/mento/Verilogv2.0.0
2020-2021https://blog.openzeppelin.com/celo-contracts-audit/OpenZeppelinv1.0.0
diff --git a/developers/smart-contracts/bipoolmanager.md b/developers/smart-contracts/bipoolmanager.md new file mode 100644 index 0000000..edfbe68 --- /dev/null +++ b/developers/smart-contracts/bipoolmanager.md @@ -0,0 +1,98 @@ +# BiPoolManager + +{% hint style="info" %} +This section describes the solidity internals of the BiPoolManager and is intended for smart contract developers. Consumers of the protocol will normally use the [SDK](../mento-sdk/) to interact with the protocol. If you want to learn more about the overall design check the [Asset Exchanges ](../../protocol-concepts/asset-exchanges/)section. +{% endhint %} + +{% embed url="https://github.com/mento-protocol/mento-core/blob/main/contracts/swap/BiPoolManager.sol" %} +BiPoolManager.sol +{% endembed %} + +**BiPoolManager** is the first implementation of an [IExchangeProvider](https://github.com/mento-protocol/mento-core/blob/main/contracts/interfaces/IExchangeProvider.sol) which manages virtual asset pools that consist of two assets. It is responsible for managing pools and using their state to price swaps. It also checks if trading is allowed or suspended as decided by the on-chain circuit breaker via the [BreakerBox](breakerbox.md) contract. + +### Pool Structures + +The `PoolExchange` and `PoolConfig` structures are the underlying data structures used by the BiPoolManager to implement a vAMM bi-pool (i.e. a pool with two assets). + +{% embed url="https://github.com/mento-protocol/mento-core/blob/develop/contracts/interfaces/IBiPoolManager.sol#L19-L41" %} +Structure definition +{% endembed %} + +### PoolExchange + +```solidity +struct PoolExchange { + address asset0; + address asset1; + IPricingModule pricingModule; + uint256 bucket0; + uint256 bucket1; + uint256 lastBucketUpdate; + PoolConfig config; +} +``` + +
FieldTypeDescription
asset0addressERC20 token address of the 1st asset in the pair. This can only be a StableToken registered with the Reserve.
asset1addressERC20 token address of the 2nd asset in the pair. This can be either a StableToken or any Mento Collateral asset registered with the Reserve.
pricingModuleIPricingModuleThe vAMM pricing function, a contract that implements IPricingModule, like ConstantProductPricingModule or ConstantSumPricingModule
bucket0uint256The amount of asset0 tokens in the pool, updates as a result of swaps and bucket resets.
bucket1uint256The amount of asset1 tokens in the pool, updates as a result of swaps and bucket resets.
lastBucketUpdateuint256Timestamp of the last bucket reset.
configPoolConfigSome extra configuration items are stored in a separate struct because of Solidity version limitations.
+ +### PoolConfig + +```solidity +struct PoolConfig { + FixidityLib.Fraction spread; + address referenceRateFeedID; // rateFeedID of the price that this pool follows (i.e. it's reference rate) + uint256 referenceRateResetFrequency; + uint256 minimumReports; + uint256 stablePoolResetSize; +} +``` + +
FieldTypeDescription
spreadFixidityLib.FractionThe spread or fee charged on swaps
referenceRateFeedIDaddressThe oracle rateFeedID used as a reference rate for the asset0/asset1 pair.
referenceRateResetFrequencyuint256How often the buckets reset to the reference rate.
minimumReportsuint256The amount of on-chain reports required in order to trust the reference rate.
stablePoolResetSizeuint256The value that bucket0 resets to when a bucket update happens.
+ +### Discovering Exchanges + +```solidity +IExchangeProvider.Exchange[] memory exchanges = biPoolManager.getExchanges(); +bytes32 exchangeId = exchanges[0].exchangeId; +address asset0 = exchanges[0].assets[0]; +address asset1 = exchanges[0].assets[1]; +``` + +This returns the generic exchange structures that are shared between all implementers of the **IExchangeProvider** interface, this is why the `assets` is an array, to account for potential 3-asset pools in the future. + +You can then also query the internal representation: + +```solidity +IBiPoolManager.PoolExchange pool = biPoolManager.getPoolExchange(exchangeId); +``` + +### Estimating Swaps + +```solidity +uint256 amountOut = biPoolManager.getAmountOut( + exchangeId, + assetIn, + assetOut, + amountIn +) +``` + +This function calculates the expected output tokens you will receive for a given amount of input tokens. It is what the Broker uses internally in its own [estimating swaps function](broker.md#estimating-swaps). + +There is also `getAmountIn` which calculates the required input tokens needed to receive a given amount of output tokens. + +### Executing Swaps + +```solidity +uint256 amountOut = biPoolManager.swapIn( + exchangeId, + assetIn, + assetOut, + amountIn +); +``` + +This function executes, in that it prices the swap and, specifically when interacting with PoolExchanges utilizing the ConstantProduct pricing module, updates the virtual bucket sizes. However, it’s important to note that for PoolExchanges configured with the ConstantSum pricing module, bucket sizes remain unchanged during swaps. The Broker uses the return value to determine how many output tokens to transfer to the initiator for the input tokens received. Similarly, there's a swapOut function that fixes the output tokens and returns a variable amount of input tokens required. + +{% hint style="info" %} +Both the `swapIn` and `swapOut` functions on the BiPoolManager only deal with virtual token amounts. The Broker is responsible for making sure that the initiator has actually given the protocol the tokens required or that the Reserve has enough tokens to pay the initator. +{% endhint %} diff --git a/developers/smart-contracts/breakerbox.md b/developers/smart-contracts/breakerbox.md new file mode 100644 index 0000000..e8fd7e6 --- /dev/null +++ b/developers/smart-contracts/breakerbox.md @@ -0,0 +1,23 @@ +# BreakerBox + +**BreakerBox**[ ](broken-reference)is an on-chain circuit breaker for oracles. It maintains a state for each price feed, whether trading is allowed or suspended. It is modular by design and allows for flexible addition and deletion of price feeds and individual breaking logic. Its conditions are checked and breakers are triggered if necessary by newly reported rates in SortedOracles.sol. For each requested swap, BiPoolManager.sol checks against this contract whether trading a specific pair is currently allowed or suspended. + +{% embed url="https://github.com/mento-protocol/mento-core/blob/main/contracts/oracles/BreakerBox.sol" %} +BreakerBox.sol +{% endembed %} + +### MedianDeltaBreaker + +**MedianDeltaBreaker** is a circuit breaker that trips when the current median oracle rate compared to an exponential moving average over previous median rates exceeds a configured relative threshold. + +{% embed url="https://github.com/mento-protocol/mento-core/blob/main/contracts/oracles/breakers/MedianDeltaBreaker.sol" %} +MedianDeltaBreaker.sol +{% endembed %} + +### ValueDeltaBreaker + +**ValueDeltaBreaker** is a circuit breaker that trips when the current median oracle rate compared to a fixed reference rate exceeds a configured relative threshold. + +{% embed url="https://github.com/mento-protocol/mento-core/blob/main/contracts/oracles/breakers/ValueDeltaBreaker.sol" %} +ValueDeltaBreaker.sol +{% endembed %} diff --git a/developers/smart-contracts/broker.md b/developers/smart-contracts/broker.md new file mode 100644 index 0000000..f39cd8c --- /dev/null +++ b/developers/smart-contracts/broker.md @@ -0,0 +1,65 @@ +# Broker + +{% hint style="info" %} +This section describes the solidity internals of the Broker and is intended for smart contract developers. Consumers of the protocol will normally use the [SDK](../mento-sdk/) to interact with the protocol. If you want to learn more about the overall design check the [Asset Exchanges](../../protocol-concepts/asset-exchanges/) section. +{% endhint %} + +{% embed url="https://github.com/mento-protocol/mento-core/blob/main/contracts/swap/Broker.sol" %} +Broker.sol +{% endembed %} + +The **Broker** is the entry point for interacting with the protocol. It is responsible for managing reserve assets and is the only contract with spender rights of the reserve as well as minting and burning rights over stable assets. For pricing trades, it relies on exchange providers like BiPoolManager. When executing swaps, it enforces trading limits. The Broker also exposes a burn function for burning stable tokens without being subject to trading limits or regular exchange operations. + +### Discovering Exchanges + +```solidity +address[] memory exchangeProviders = broker.getExchangeProviders(); +IExchangeProvider exchangeProvider = IExchangeProvider(exchangeProviders[0]); +IExchangeProvider.Exchange[] memory exchanges = exchangeProvider.getExchanges(); +bytes32 exchangeId = exchanges[0].exchangeId; +address asset0 = exchanges[0].assets[0]; +address asset1 = exchanges[0].assets[1]; +``` + +The `getExchangeProviders` function on the broker is used to list all registered exchange providers. We then cast the first one as an **IExchangeProvider** interface and make use of its `getExchanges` to discover the configured exchanges. We then use that to find the id of a desired exchange. This is a contrived example as the discoverability part is best done off-chain via [the SDK](../mento-sdk/). + +### Estimating Swaps + +```solidity +uint256 amountOut = broker.getAmountOut( + exchangeProvider, + exchangeId, + assetIn, + assetOut, + amountIn +) +``` + +This function calculates the expected output tokens you will receive for a given amount of input tokens. To call the function you need to pass the following: + +* The **exchangeProvider** address which is used for pricing the trade +* The **exchangeId** (bytes32) that the exchange provider would know about +* The **assetIn** address of the ERC20 token you want to give to the protocol +* The **assetOut** address of the ERC20 token you want to get from the protocol +* The **amountIn** (uint256) of **assetIn** that you want to pay + +There is also `getAmountIn` which calculates the required input tokens needed to receive a given amount of output tokens. + +### Executing Swaps + +```solidity +uint256 amountOut = broker.swapIn( + exchangeProvider, + exchangeId, + assetIn, + assetOut, + amountIn, + minAmountOut +); +``` + +This function executes a swap and returns the number of output tokens that the initiator received. In order to execute the function, the initiator must give prior approval to the `broker` to transfer `amountIn` tokens of `assetIn` from the initiator. + +The function takes in almost the same arguments as the one for [estimating swaps ](broker.md#estimating-swaps)with the addition of `minAmountOut` that is used for slippage control by causing the function to revert if the final `amountOut` doesn't meet the requirement. + +There is also a `swapOut` function that swaps a variable amount of input tokens for a given amount of output tokens. The slippage parameter becomes `maxAmountIn`, limiting how many tokens the broker can spend for a fixed output. diff --git a/developers/smart-contracts/pricing-modules.md b/developers/smart-contracts/pricing-modules.md new file mode 100644 index 0000000..ef6dc93 --- /dev/null +++ b/developers/smart-contracts/pricing-modules.md @@ -0,0 +1,44 @@ +# Pricing Modules + +Pricing Modules are utility contracts that implement the IPricingModule interface and are used by the BiPoolManager during swaps to price the swaps. A pricing module has to implement two functions: + +```solidity +uint256 amountOut = pricingModule.getAmountOut(inBucket, outBucket, spread, amountIn); +uint256 amountIn = pricingModule.getAmountIn(inBucket, outBucket, spread, amountOut); +``` + +{% embed url="https://github.com/mento-protocol/mento-core/blob/main/contracts/interfaces/IPricingModule.sol" %} +IPricingModule.sol +{% endembed %} + +### ConstantSumPricingModule + +$$ +X * p + Y = K \newline +(X +x)*p + Y-y = K +$$ + +Where $$X$$is the bucket size of _TokenIn,_ $$Y$$is the bucket size of _TokenOut,_ $$x$$ is the _amountIn,_ $$y$$ is the amountOut, $$K$$is a constant, and $$p$$ is the value of _tokenIn_ quoted in _tokenOut_. + + + +**ConstantSumPricingModule** is an IPricingModule that implements a constant-sum pricing formula for a two-asset pool. + +{% embed url="https://github.com/mento-protocol/mento-core/blob/main/contracts/swap/ConstantSumPricingModule.sol" %} +ConstantSumPricingModule.sol +{% endembed %} + +### ConstantProductPricingModule + +$$ +X*p*Y=K \newline +(X + x)*p*( Y - y) = K +$$ + +Where $$X$$is the bucket size of _TokenIn,_ $$Y$$is the bucket size of _TokenOut,_ $$x$$is the _amountIn,_ $$y$$ is the amountOut, $$K$$is a constant, and $$p$$ is the value of _tokenIn_ quoted in _tokenOut_. + +**ConstantProductPricingModule** is an IPricingModule that implements a constant-product pricing formula for a two-asset pool. + +{% embed url="https://github.com/mento-protocol/mento-core/blob/main/contracts/swap/ConstantProductPricingModule.sol" %} +ConstantProductPricingModule.sol +{% endembed %} diff --git a/developers/smart-contracts/reserve.md b/developers/smart-contracts/reserve.md new file mode 100644 index 0000000..6a17336 --- /dev/null +++ b/developers/smart-contracts/reserve.md @@ -0,0 +1,7 @@ +# Reserve + +**Reserve** stores and manages any ERC-20 Mento reserve asset on the Celo blockchain. Assets can be accessed and controlled only by the Broker as well as a [MultiSig](../../protocol-concepts/reserve.md#reserve-assets). + +{% embed url="https://github.com/mento-protocol/mento-core/blob/main/contracts/swap/Reserve.sol" %} +Reserve.sol +{% endembed %} diff --git a/developers/smart-contracts/sortedoracles.md b/developers/smart-contracts/sortedoracles.md new file mode 100644 index 0000000..5358682 --- /dev/null +++ b/developers/smart-contracts/sortedoracles.md @@ -0,0 +1,28 @@ +# SortedOracles + +**SortedOracles** stores and maintains the state of oracle reports. Oracle clients insert their rates into a sorted linked list and the contract checks newly inserted rates against the on-chain circuit breaker BreakerBox.sol. If valid, the rate can be used by the protocol to price swaps, otherwise, trading will be halted. + +### Unique Rate Feed Identifiers + +Each oracle rate, internally called rate feed, is uniquely identified by a `rateFeedID`. It is used when adding oracle rates to the [SortedOracle smart contract](sortedoracles.md) by calling the [`addOracle`](https://github.com/mento-protocol/mento-core/blob/develop/contracts/SortedOracles.sol#L152) function in a Celo governance proposal: + +```solidity +addOracle(address token, address oracleAddress) +``` + +For `CELO/cStable` rate feeds, the unique identifier is the address of the stable token. Since this doesn't work for more than one pair including the same stable token, which was not initially planned, a new formula is used to create unique rate feed identifiers for rate feeds other than `CELO/cStable`. + +These identifiers can be derived using the following formula: + +```solidity +address(uint160(uint256(keccak256(${asset0asset1})))) +``` + +For example, `USDCUSD` inserted gives the following formula: + +```solidity +address(uint160(uint256(keccak256("USDCUSD")))) +// == 0xA1A8003936862E7a15092A91898D69fa8bCE290c +``` + +An example can be found in this [Celo Governance Proposal](https://github.com/celo-org/governance/blob/roman/add-usdc-oracles/CGPs/cgp-0071.md#status). diff --git a/developers/smart-contracts/stabletoken.md b/developers/smart-contracts/stabletoken.md new file mode 100644 index 0000000..e3c8751 --- /dev/null +++ b/developers/smart-contracts/stabletoken.md @@ -0,0 +1,7 @@ +# StableToken + +**StableToken** implements ERC-20 tokens and Celo-specific features for stable assets. Each stable asset has its own contract, with StableToken.sol for the Celo Dollar, StableTokenEUR.sol for the Celo Euro, and so forth for new stable assets. + +{% embed url="https://github.com/mento-protocol/mento-core/blob/main/contracts/legacy/StableToken.sol" %} +StableToken.sol +{% endembed %} diff --git a/developers/smart-contracts/tradinglimits.md b/developers/smart-contracts/tradinglimits.md new file mode 100644 index 0000000..a8405c0 --- /dev/null +++ b/developers/smart-contracts/tradinglimits.md @@ -0,0 +1,56 @@ +# TradingLimits + +The `TradingLimits` library provides data structs and utility functions for defining and verifying trading limits on the net flow of an asset. It supports three types of limits: + +1. L0: A time-window-based limit that verifies whether the net flow is within the specified limit0 range, resetting every timespan0 seconds. +2. L1: A time-window-based limit that verifies whether the net flow is within the specified limit1 range, resetting every timespan1 seconds. +3. LG: A global (or lifetime) limit that ensures the net flow is within the specified limitGlobal range and doesn't reset until the limit is disabled. + +This library is intended to be consumed by other contracts, with all functions marked as `internal` and `pure` or `view` for inlining during compilation to improve gas efficiency. + +### Structs + +#### Config + +```solidity + struct Config { + uint32 timestep0; + uint32 timestep1; + int48 limit0; + int48 limit1; + int48 limitGlobal; + uint8 flags; + } + +``` + +The `Config` struct stores the configuration parameters for the trading limits. It is designed to be packed into a single storage slot for efficiency. The struct contains the following fields: + +| Attribute | Type | Description | +| ----------- | ------ | ------------------------------------------------------------------------------------------- | +| timestep0 | uint32 | Time in seconds for the timewindow-based limit L0, netflow0 resets every timestep0 seconds. | +| timestep1 | uint32 | Time in seconds for the timewindow-based limit L1, netflow1 resets every timestep1 seconds. | +| limit0 | int48 | Limit for the timewindow-based limit L0. | +| limit1 | int48 | Limit for the timewindow-based limit L1. | +| limitGlobal | int48 | Limit for the global (or lifetime) limit LG. | +| flags | uint8 | Bitwise flags that specify which limits are enabled: L0, L1, and LG. | + +#### State + +```solidity + struct State { + uint32 lastUpdated0; + uint32 lastUpdated1; + int48 netflow0; + int48 netflow1; + int48 netflowGlobal; + } +``` + +The `State` struct is used to keep track of the trading limits and their respective netflows for a given asset. It contains information about the netflows for each limit (L0, L1, and LG) as well as the timestamps when the limits were last reset. + +
AttributeTypeDescription
lastUpdated0uint32Timestamp of the last reset for the netflow0.
lastUpdated1uint32Timestamp of the last reset for the netflow1.
netflow0int48Netflow for the time-window-based limit L0, resets every timespan0 seconds.
netflow1int48Netflow for the time-window-based limit L1, resets every timespan1 seconds.
netflowGlobalint48Netflow for the global (or lifetime) limit LG, doesn't reset until the limit is disabled.
+ +\ + + diff --git a/economics/research.md b/economics/research.md new file mode 100644 index 0000000..dad400f --- /dev/null +++ b/economics/research.md @@ -0,0 +1,14 @@ +# Research + +### Stability Analysis + +A stability analysis was conducted that investigates the stability characteristics of Mento stable value assets through a series of simulations under various market conditions. In this analysis, simulation techniques are used to understand the behavior of the protocol and its potential vulnerabilities over a wide range of possible developments — including severe shocks, attacks, extremely positive and extremely negative market movements. A wide range of possibilities was modeled, rather than relying on historical data, because the space is too new to rely on historical prices for modeling purposes. + +A good introduction into the stability analysis - especially for users not used to reading economic research papers - can be found in this blog post (Mento stable assets were previously called Celo stable assets): + +{% embed url="https://blog.celo.org/a-look-at-the-celo-stability-analysis-white-paper-part-1-23edd5ef8b5" %} + +And here you can find the full stability analysis research paper (Mento stable assets were previously called Celo stable assets, and Mento Labs spun out of cLabs): + +{% embed url="https://celo.org/papers/Celo_Stability_Analysis.pdf" %} + diff --git a/economics/risks.md b/economics/risks.md new file mode 100644 index 0000000..5d19fbd --- /dev/null +++ b/economics/risks.md @@ -0,0 +1,22 @@ +# Risks + +### Introduction + +As human behavior and financial markets are subject to randomness, there are risks involved with the creation of stable assets. + +### Economic and Reserve Risks + +The primary risk to Celo Dollar stability is a scenario in which there is a decrease in demand for Celo Dollars greater than the total value of the reserves. In such a scenario, the protocol would be unable to handle a sufficient contraction amount to meet decreased demand. A secondary risk is a scenario in which there exists enough value in the reserves to handle a contraction in demand, but not enough market liquidity to sell the amount of a crypto asset quickly enough to handle the contraction. Estimates of the likelihood of either of these risks under the given modeling assumptions can be found in the[ stability analysis](https://celo.org/papers/stability). + +### Oracle Risks + +Mento oracles enable a list of oracle providers to report and calculate the median of the reported values. One individual provider can not influence the median on their own. The only way to complete control would be to control half the oracles. Although there are additional mitigations like the off-chain and on-chain circuit breaker and trading limits in place, the community will have to monitor whether community-run oracles are behaving properly. + +### Blockchain Risk + +The Mento protocol consists of a set of smart contracts that run on the Celo blockchain. Should the Celo blockchain stall or consensus be compromised, the Mento Protocol could not run correctly anymore. + +### Smart Contract Risk + +Smart Contracts on a blockchain can have vulnerabilities. This risk is being addressed via internal and external code audits. + diff --git a/economics/stability.md b/economics/stability.md new file mode 100644 index 0000000..4d212ac --- /dev/null +++ b/economics/stability.md @@ -0,0 +1,104 @@ +# Stability + +{% hint style="info" %} +This is a continuation of the introduction to the Mento exchange mechanism in the Protocol Concepts section: [stability.md](../protocol-concepts/stability.md "mention") +{% endhint %} + +### Introduction + +In theory, a stablecoin will keep its peg as long as demand and supply meet at the target price. A stablecoin with an excess of supply will lead to it being devalued; a stablecoin with a deficit of supply will lead to exceeding the value of its peg. + +
+ +An exploration of the economics behind Mento stable assets, previously called Celo stable assets, can be found in the following article: + +{% embed url="https://blog.celo.org/zooming-in-on-the-celo-expansion-contraction-mechanism-446ca7abe4f" %} + +### Mechanism + +Mento stable assets follow an elastic coin supply rule. The Mento Exchange Mechanism sets incentives to allow everyone to stabilize the value of the asset by adjusting supply to match demand. The mechanism balances two conflicting goals: + +1. Liquidity: Allowing users to react to large and abrupt changes in demand by allowing large and abrupt changes in supply. +2. Protecting the reserve from oracle price manipulation. + +### Typical Economic Oracle Exploit Scenario + +The typical economic exploit scenario for Mento would look like the following: + +1. Malicious actor manipulates centralized exchange prices for CELO by driving the price up, which results in manipulated oracle reports +2. Malicious actor exchanges Mento stable assets for CELO very cheaply +3. Malicious actor exchanges Mento stable assets for other assets or fiat currencies, making a profit at the expense of the Mento reserve and other Mento stable asset holders. + +This exploit scenario could either be launched with the intention to make a profit or to just damage the protocol. To mitigate this risk by making this sort of attack unprofitable, the protocol limits the rate of possible expansion and contraction. The rate of expansion and contraction of Mento stable asset supply is limited in a way that manipulating prices on centralized exchanges would be more expensive than what you could get out of the Mento reserve over time. The downside that comes with it is that this limits the possible speed of expansion and contraction, in a worst-case leading to an imbalance of supply and demand and thus a de-peg. + +### Mitigating Oracle Risk + +Mento uses a virtual automated market maker (vAMM) setup for pricing exchanges between Mento stable and collateral assets. There is no user-provided liquidity like on decentralized exchanges (DEXs), instead, the vAMM is only used for pricing, while exchanges happen directly against the reserve. In a vAMM pool, there are two 'buckets' of assets, one for the stable, and one for the collateral asset. The bucket sizes are now chosen in a way that typical economic exploit scenarios like oracle attacks or price manipulation on centralized exchanges would not be profitable. Technically, this is implemented by bucket sizes that reset at a specified frequency, usually every five minutes. + +### Slippage + +Below you can find a summary table of different slippage levels for Mento cUSD/CELO and cUSD/USDC pools configured with deployment parameters ([parameters.md](../developers/deployments/parameters.md "mention")). These values are for a 5min bucket reset period, which can also be understood as the speed of contraction per 5 minutes. + +
Exchange0.02% slippage2% slippage25% slippage
cUSD/Celo-~165_600 cUSD~2_440_800 cUSD
cUSD/USDC11_988_000 cUSD--
+ +In the following paragraphs, you can find more detailed information about what levels of slippage will be incurred in Mento pools. We will present some figures related to slippage and possible contraction amounts over time, which can also be interpreted as speed of contraction. + +Let us look at the cUSD/CELO constant product pool configured to + +```notebook-python +spread = 0.0025 # 0.25% +reset_frequency = 5 # 5 minutes +celo_usd_price = 0.6 +stable_asset_bucket_size = 7_200_000 +``` + +which is what the pool has initially been deployed with, as in [parameters.md](../developers/deployments/parameters.md "mention"). The spread is determined by the constant product formula, implemented as + +$$ +amountOut = \frac{tokenOutBucketSize * amountIn * (1-spread) } {tokenInBucketSize + amountIn * (1-spread)} +$$ + +contractingWhat you can see in the plot below is the slippage a trade would experience on the y-axis for a given cUSD trade size on the x-axis. A \~165\_600 cUSD exchange to CELO would experience 2% slippage, while a \~2\_440\_800 cUSD exchange would experience 25% slippage for one 5min bucket reset period. When thinking about speed of contraction, at 2% slippage the Mento cUSD/CELO pool allows contracting at a speed of \~165\_600 cUSD/5min, and at 25% slippage at a speed of \~2\_440\_800 cUSD/5min. + +

cUSD/Celo slippage per 5 minute bucket update

+ +The next plot shows how much cUSD can be exchanged or contracted with CELO at 2% slippage including spread over time. + +

cUSD/Celo amount of cUSD contraction at 2% slippage over time

+ +Let us look at the cUSD/axlUSDC constant sum pool configured to + +```notebook-python +spread = 0.0002 # 0.25% +reset_frequency = 5 # 5 minutes +celo_usd_price = 1 +stable_asset_bucket_size = 12_000_000 +``` + +which is what the pool has initially been deployed with, as in [parameters.md](../developers/deployments/parameters.md "mention"). The slippage is determined by the constant sum formula, implemented as + +$$ +amountOut = amountIn * (1 - spread) +$$ + +What you can see in the plot below is the slippage a trade would experience on the y-axis for a given cUSD trade size on the x-axis. Since this is a constant sum pool, the whole bucket size of 12\_000\_000 cUSD can be traded at zero slippage, only paying the spread of 0.02%. When thinking about speed of contraction, at 0.02% slippage the Mento cUSD/axlUSDC pool allows contracting at a speed of \~12\_000\_000 cUSD/5min. + +

cUSD/USDC slippage per 5 minute bucket update

+ +The next plot shows how much cUSD can be exchanged or contracted with USDC at 0.02% slippage including spread over time. + +

amount of cUSD contraction at 2% slippage over time

+ +### Economics Parameters + +Here you can find a list of parameters that determine the slippage and speed of contraction over time: + +* Reference rate reset parameter (vAMM bucket updates) in time frequency: [https://github.com/mento-protocol/mento-deployment/blob/main/script/upgrades/MU01/governance/Config.sol#L47](https://github.com/mento-protocol/mento-deployment/blob/main/script/upgrades/MU01/governance/Config.sol#L47) +* Stable pool bucket reset size in the number of tokens: [https://github.com/mento-protocol/mento-deployment/blob/main/script/upgrades/MU01/governance/Config.sol#L61](https://github.com/mento-protocol/mento-deployment/blob/main/script/upgrades/MU01/governance/Config.sol#L61) +* Pool spread, which contributes to slippage/fees paid: [https://github.com/mento-protocol/mento-deployment/blob/main/script/upgrades/MU01/governance/Config.sol#L61](https://github.com/mento-protocol/mento-deployment/blob/main/script/upgrades/MU01/governance/Config.sol#L61) +* Trading limits + * 5min: [https://github.com/mento-protocol/mento-deployment/blob/main/script/upgrades/MU01/governance/Config.sol#L132](https://github.com/mento-protocol/mento-deployment/blob/main/script/upgrades/MU01/governance/Config.sol#L132) + * 1 hour: [https://github.com/mento-protocol/mento-deployment/blob/main/script/upgrades/MU01/governance/Config.sol#L137](https://github.com/mento-protocol/mento-deployment/blob/main/script/upgrades/MU01/governance/Config.sol#L127) + * global: [https://github.com/mento-protocol/mento-deployment/blob/main/script/upgrades/MU01/governance/Config.sol#L142](https://github.com/mento-protocol/mento-deployment/blob/main/script/upgrades/MU01/governance/Config.sol#L142) + +The current on-chain parameters can be found with the [addresses.md](../developers/deployments/addresses.md "mention")and respective block explorers. The deployed parameters can be found in the [parameters.md](../developers/deployments/parameters.md "mention") section. diff --git a/mento-protocol/quick-links.md b/mento-protocol/quick-links.md new file mode 100644 index 0000000..ef57f94 --- /dev/null +++ b/mento-protocol/quick-links.md @@ -0,0 +1,26 @@ +--- +description: Quick access to all things Mento ecosystem +--- + +# Quick Links + +## Mento Protocol + +* [Website](https://mento.org)[ (mento.org)](https://mento.org) +* [App (app.mento.org)](https://app.mento.org/) +* [Deployment Addresses](../developers/deployments/addresses.md) +* [Reserve (reserve.mento.org)](https://reserve.mento.org) +* [Mento Protocol on GitHub](https://github.com/mento-protocol) +* [Mento Oracle (previously Celo Oracles) GitHub repository](https://github.com/celo-org/celo-oracle) +* [Mento Protocol on Twitter](https://twitter.com/MentoProtocol) +* [Mento Discord Invitation](https://discord.gg/gb7B5Ux4n8) + +## Mento Labs + +* [Website (mentolabs.xyz)](https://mentolabs.xyz) +* [Mento Labs on Twitter](https://twitter.com/mento\_labs) + +## Celo Governance + +* [Celo Governance Docs](http://127.0.0.1:5000/s/TTxQdBUOJwGkQLpLLxm8/developers/mento-core/smart-contracts/breakerbox/mediandeltabreaker) +* [Celo Governance Proposals by StakeID](https://celo.stake.id/#/) - A good website to quickly see governance proposals and election results diff --git a/mento-protocol/what-why-who-mento.md b/mento-protocol/what-why-who-mento.md new file mode 100644 index 0000000..675e4d1 --- /dev/null +++ b/mento-protocol/what-why-who-mento.md @@ -0,0 +1,19 @@ +# What, why, who Mento? + +### What? + +Mento is a decentralized and transparent protocol that enables the creation of stable value digital assets, such as assets that track the value of fiat currencies (commonly referred to as ‘stablecoins’). The goal of Mento is to support the real-world adoption of digital currencies by enabling the creation of stable value assets for users around the world. Mento is currently live on the Celo blockchain where it operates the Celo Dollar (cUSD), Celo Euro (cEUR), and the Celo Brazilian Real (cReal). All Mento assets are fully collateralized with a diversified portfolio of exogenous crypto assets. + +### Why? + +Stable value digital assets are a crucial building block in the web3 economy as they enable a stable store and transfer of value and provide for fast, secure, and low-cost transactions. + +More developed web3 markets also call for a more diverse stable value asset landscape to serve the growing demand for remittances, mobile payments, saving, lending, and borrowing in local currencies. + +The Mento Protocol aims to provide a solution: A multi-currency stable asset ecosystem to enable real-world usability. + +### Who? + +While Mento Protocol is a Celo ecosystem project with a wide array of contributors, it was initially developed and is maintained by the team at [Mento Labs](https://www.mentolabs.xyz/). + +Mento Labs is a digital asset solutions company based in Berlin with a team of economists, engineers, and web3 experts dedicated to the development of the open protocol Mento. Mento Labs also helps to design sustainable assets for partners, from settlement currencies over incentive tokens to stable assets. diff --git a/protocol-concepts/asset-exchanges/README.md b/protocol-concepts/asset-exchanges/README.md new file mode 100644 index 0000000..eb23d75 --- /dev/null +++ b/protocol-concepts/asset-exchanges/README.md @@ -0,0 +1,13 @@ +--- +description: The Mento components that orchestrate asset exchanges +--- + +# Asset exchanges + +The Mento Protocol provides a mechanism to exchange assets with the reserve. This mechanism serves two roles. The first role is in **service of the stability** of the protocol by providing arbitrageurs a way to trade stables assets with the reserve at a protocol-enforced rate with respect to the collateral, thus closing the arbitrage cycle with other markets (DEXs or CEXs) and enforcing the stable asset pegs. The second role is as a **distribution mechanism** for mento stable assets by providing low slippage, and high bandwidth expansion capability against forms of collateral that support that. + +Asset swaps in the Mento Protocol happen with the aid of these components: + +* The [**Broker**](broker.md) is responsible for orchestrating exchanges, managing the treasury, and enforcing trading limits. +* [**Exchange providers**](exchange-providers.md) are abstract components responsible for pricing asset swaps, that implement a unified interface. The **Broker** relies on them when orchestrating the trades. +* The [**BiPoolManager**](../../developers/smart-contracts/bipoolmanager.md) is the first **exchange provider** implemented. It is a generalization of the vAMM pools in Mento v1.0.0. diff --git a/protocol-concepts/asset-exchanges/bipoolmanager.md b/protocol-concepts/asset-exchanges/bipoolmanager.md new file mode 100644 index 0000000..6095508 --- /dev/null +++ b/protocol-concepts/asset-exchanges/bipoolmanager.md @@ -0,0 +1,17 @@ +--- +description: Exchange provider with two-asset virtual automated market maker pools +--- + +# BiPoolManager + +The **BiPoolManager** is an [exchange provider ](exchange-providers.md)that generalizes the [vAMM](bipoolmanager.md#vamm) implementation in Mento v1's Exchanges. It manages asset pools containing a pair of Mento assets, which can be either stable-to-collateral or stable-to-stable. A pool can be configured to use either a constant sum or a constant product pricing function via [pricing modules.](bipoolmanager.md#pricing-modules) + +### vAMM + +An automated market maker (AMM) is a type of decentralized exchange (DEX) that enables the automatic exchange of digital assets. Typically AMMs rely on user-provided liquidity pools, which hold assets, that can be exchanged in one or more smart contracts. AMMs rely on a specific market-maker function that automatically adjusts the price of assets based on the liquidity pool reserves. + + Virtual automated market makers (vAMMs) are built on the same concepts as AMMs; however, there is no user-provided liquidity, and the vAMM holds no assets. Virtual automated market makers also employ market-maker functions to determine the price of assets that users can exchange. + +### Pricing Modules + +A market maker function is a mathematical formula used by AMMs & vAMMs to determine the price of assets in a pool and to determine the levels of available liquidity. Several market maker functions exist, including constant product, constant sum, and constant mean. Mento pricing modules are an abstraction over these market maker functions, allowing Mento exchanges to use any market maker function without changing the underlying code structure. diff --git a/protocol-concepts/asset-exchanges/broker.md b/protocol-concepts/asset-exchanges/broker.md new file mode 100644 index 0000000..b6ea52e --- /dev/null +++ b/protocol-concepts/asset-exchanges/broker.md @@ -0,0 +1,9 @@ +# Broker + +The **Broker** is responsible for orchestrating swaps in the Mento Protocol. It does that by fulfilling three main responsibilities: + +* **Discoverability**: It maintains a list of all [**exchange providers**](exchange-providers.md) registered in the system. +* **Treasury management:** It has spending rights on the [**Reserve**](../reserve.md) and can mint and burn any stable asset in the system, thus it is responsible for moving around assets during a trade. +* **Safety**: In service of [stability](../stability.md), it enforces [trading limits](trading-limits.md) in the protocol, constraining the volume of assets that can be traded over time. + +While it is responsible for moving around assets during a swap, it doesn't know how to price swaps. For that, it relies on [**exchange providers**](exchange-providers.md). These abstract components implement a unified interface and can be plugged into the **Broker** to provide exchanges between two or more assets. The first exchange provider that we implement is the [BiPoolManager](../../developers/smart-contracts/bipoolmanager.md). diff --git a/protocol-concepts/asset-exchanges/exchange-providers.md b/protocol-concepts/asset-exchanges/exchange-providers.md new file mode 100644 index 0000000..92c69cc --- /dev/null +++ b/protocol-concepts/asset-exchanges/exchange-providers.md @@ -0,0 +1,5 @@ +# Exchange Providers + +The concept of exchange providers allows us to abstract how asset exchanges are priced from the [**Broker's**](broker.md) responsibilities. Given an _in asset_ and an _out asset_ and the _amount_ one wants to trade, an exchange provider can employ any mechanism in order to price the respective trade and manage its internal state as a result of executing such trades. It does this entirely virtually and never actually holds assets. + +The first exchange provider that we make use of in the Mento protocol is the [**BiPoolManager**](bipoolmanager.md)**.** diff --git a/protocol-concepts/asset-exchanges/trading-limits.md b/protocol-concepts/asset-exchanges/trading-limits.md new file mode 100644 index 0000000..144ed43 --- /dev/null +++ b/protocol-concepts/asset-exchanges/trading-limits.md @@ -0,0 +1,15 @@ +# Trading Limits + +The Mento stability mechanism relies on the ability to contract and expand the supply of Mento stable assets by allowing everyone to exchange stable assets with the Reserve against collateral assets and the other way around. The rate of expansion and contraction (i.e. _volume that can be traded in a unit of time_) is highly dependent on the **volatility** and the **liquidity** of the collateral in the pair. For example, when trading cUSD for Celo with the Reserve, the amount that we can trade between two vAMM bucket updates has to be significantly lower than the amount we are able to trade when trading cUSD against USDC. This is done in order to protect against oracle manipulation risk, which is greatly reduced when trading cUSD against USDC. + +In Mento V1 the vAMM bucket sizes have two distinct uses: (1) they enable price finding between oracle updates and (2) they act as an effective trading limit by introducing slippage. This works quite well but it makes it hard to fine-tune the slippage function. Introducing trading limits, allows us to use the bucket sizes only for price finding. This means we can increase the bucket sizes, thus reducing the average slippage between two oracle updates, while still limiting the amount that can be traded between two bucket updates. + +In a broader sense, we can also apply the trading limits to safeguard the protocol by enforcing daily or global limits. Governance can configure trading limits on a specific combination of token and exchange – for example, a limit can be set on the amount of cUSD that flows in the cUSD/CELO exchange, while another limit can be set on the amount of cUSD that flows through the cUSD/USDC exchange. Each token and exchange combination can have two **time-based limits** (**L0** and **L1**) and one **global limit** (**LG**). + +L0 and L1 are time-based limits that monitor the net flow of a particular asset and ensure that it doesn’t exceed the specified limit within a set time frame. Typically we've set **L0** at 5 minutes, to enforce how much can be traded between two bucket updates, and **L1** to a day as a fail-safe. + +In contrast, **LG** is a global limit that remains in effect for as long as the limit is enabled and prevents the net flow of a particular asset from meeting or exceeding the configured limit. + +The Broker smart contract initiates the trading limit checks on every exchange request. Trading limits are configured in the broker contract and can only be modified by governance. + +Please check out the technical reference for more information on how the trading limits work. diff --git a/protocol-concepts/governance.md b/protocol-concepts/governance.md new file mode 100644 index 0000000..cfb9383 --- /dev/null +++ b/protocol-concepts/governance.md @@ -0,0 +1,5 @@ +# Governance + +Mento Core smart contracts are governed by the [Celo governance](https://docs.celo.org/protocol/governance) while a separate Mento governance is under development. + +A good place to view historical and ongoing governance proposals is on [Celo Stake ID](https://celo.stake.id/#/). diff --git a/protocol-concepts/on-chain-circuit-breaker.md b/protocol-concepts/on-chain-circuit-breaker.md new file mode 100644 index 0000000..12a06e4 --- /dev/null +++ b/protocol-concepts/on-chain-circuit-breaker.md @@ -0,0 +1,17 @@ +# On-Chain Circuit Breaker + +The Mento protocol relies on off-chain oracle clients to provide crucial price data such as exchange rates of a specific token against various currencies such as USD, BRL and EUR. These rates are submitted to a smart contract - [SortedOracles](https://github.com/mento-protocol/mento-core/blob/main/contracts/SortedOracles.sol), which is essential for the stability mechanism. The price data that is submitted, is potentially subject to manipulation by the entity running the oracle client or other malicious actors. The protocol includes an on-chain circuit breaker as an additional security measure to protect the mechanism from any potential manipulation attacks or extreme market volatility. + +### What is a circuit breaker? + +The circuit breaker pattern is typically used in software to prevent catastrophic cascading failures across related systems. This pattern is also adopted in TradFi markets to trigger a temporary halt in trading when a significant price movement occurs. In the context of Mento, the circuit breaker can be described as a mechanism designed to automatically halt the ability to exchange Mento assets due to a pre-defined condition being met. The use of the circuit breaker is an attempt to balance the need for market efficiency with the need to prevent catastrophic losses due to extreme events. + +### The Mento circuit breaker + +The "circuit breaker" is not a single component but a collection of components designed to identify specific market conditions and prevent further minting or burning of Mento stables if any of these conditions are met. It was built with flexibility in mind and allows the monitoring of new conditions and the integration of additional virtual asset pools in the future. + +

The Mento protocol circuit breaker & integration points

+ +For a more detailed explanation of how the circuit breaker functions and its internals, please see the developer section. + + diff --git a/protocol-concepts/oracles.md b/protocol-concepts/oracles.md new file mode 100644 index 0000000..1cd0d51 --- /dev/null +++ b/protocol-concepts/oracles.md @@ -0,0 +1,13 @@ +# Oracles + +## What are Mento Oracles? + +On blockchains, oracles bring off-chain information on-chain, making that information accessible in smart contracts. In the Mento Protocol, exchange rates from centralized cryptocurrency exchanges are used to enable the creation and exchange of stable value assets. + +Oracles usually consist of an off-chain client and one or multiple on-chain smart contracts. The Mento Protocol includes a [SortedOracles](https://github.com/mento-protocol/mento-core/blob/develop/contracts/SortedOracles.sol) smart contract which receives and stores a collection of exchange rate reports between Mento collateral assets and other currencies and makes these available to other smart contracts. The smart contract receives these exchange rates from off-chain client programs, which in turn query them from centralized cryptocurrency exchanges. + +## How does the protocol use oracles? + +Oracles on Celo for Mento are an essential part of the stability mechanism. The protocol uses the reported rates to allow the exchange of Mento collateral with stable assets at correct market prices. For this, the oracles report one exchange rate, internally also referenced as rate feed, for each exchange pair. + +

How the protocol uses oracles

diff --git a/protocol-concepts/reserve.md b/protocol-concepts/reserve.md new file mode 100644 index 0000000..9581160 --- /dev/null +++ b/protocol-concepts/reserve.md @@ -0,0 +1,33 @@ +# Reserve + +{% hint style="info" %} +This page describes the Mento Reserve conceptually, while information about holdings, asset allocation, and addresses can be found on the [Mento Reserve Website](https://reserve.mento.org/). +{% endhint %} + +### Introduction + +The Mento reserve is a diversified portfolio of crypto-assets that support the ability of the Mento protocol to allow everyone to expand and contract the supply of Mento stable assets in-line with user demand. + +
+ +### Reserve Assets + +Reserve asset selection is done by Celo governance. Reserve assets must be freely traded and settled 24/7 on liquid markets, and should be based on an open-source protocol. + +The reserve has the mandate to collateralize 110% of the Mento stable assets outstanding in the stable assets USDC and DAI and diversify the remainder into crypto assets BTC, ETH, and CELO. There is also a small experimental allocation in nature-backed assets, with the goal of supporting their adoption and liquidity. With this mandate, the Mento Protocol would be able to safely wind down all Mento stable assets in exchange for other stable assets at every moment in time. + +The live status of the reserve including asset allocation and wallet addresses can be found on the[ Mento Reserve website](https://reserve.mento.org/): + +{% embed url="https://reserve.mento.org/" %} + +### Custodians + +Celo native assets are held in the Reserve smart contract. The Mento Reserve ensures that non-CELO reserve assets are held safely through the use of approved, qualified and licensed custodians in a country that is not blacklisted by the Financial Action Task Force or subject to sanctions prohibitions. Custodians are required to make publicly available the assets they hold on behalf of the Mento Reserve to ensure that stakeholders and the broader community have full transparency with respect to reserve assets. The non-Celo native assets in custody are controlled by a MultiSig consisting of several members of the Celo and Mento communities. + + + +### Reserve Mandate + +The highest mandate of the Mento reserve is the protection of Mento stable value assets holders. Since not all reserve assets can be exchanged and held on the Celo blockchain, there is a Mento Reserve MultiSig that enforces the reserve mandate. + +The mandate currently consists of enforcing a 100% stable asset backing ([forum post](https://forum.celo.org/t/reserve-mandate-1-1-stable-value-asset-basket/3663?u=tobi), [governance decision](https://celo.stake.id/#/proposal/62)) and above that diversifying into, safely storing, and rebalancing governance-determined and allocated crypto assets. Asset Management of non-Celo assets like BTC, ETH, USDC, and DAI is conducted by the Mento Reserve MultiSig consisting of Celo and Mento community members. The actions of the Mento Reserve MultiSig can be seen and verified with the address listed on the [Mento Reserve Website](https://reserve.mento.org/). diff --git a/protocol-concepts/stability.md b/protocol-concepts/stability.md new file mode 100644 index 0000000..19f3317 --- /dev/null +++ b/protocol-concepts/stability.md @@ -0,0 +1,27 @@ +# Stability + +### Introduction + +Mento allows everyone to create and exchange crypto assets pegged to fiat currencies, baskets of goods, or other reference prices. The Mento stability protocol can be thought of as a mechanism for over-collateralized, decentralized & transparent stable assets in which a crypto reserve is used to allow users to adjust the supply of Mento stable assets in response to changes in demand. + +The protocol allows users to exchange Mento stable assets with [reserve collateral assets](https://reserve.mento.org). Users can expand the supply of a stable asset by sending one reference unit worth of a [reserve collateral asset](https://reserve.mento.org/) to the reserve and receiving one stable asset in exchange. Users can also contract the supply of a stable asset by sending one stable asset to the reserve in exchange for one reference unit worth of a [reserve collateral asset](https://reserve.mento.org/). + +

A visualization of the exchange mechanism. The Mento reserve was previously called the Celo reserve.

+ +### Exchange Mechanism + +In economic terms, Mento stable assets follow an elastic coin supply rule. The Mento Exchange Mechanism sets incentives to allow everyone to stabilize the value of the asset by adjusting supply to match demand. The over-collateralized, decentralized & transparent reserve of crypto-assets bears the risk of a decrease in stablecoin demand. In essence, the protocol shifts volatility risk from the stable asset holders to the reserve of crypto-assets. + +Let us dive into an example with the Celo Dollar: When demand for the Mento Dollar rises and the market price is above the $1 peg, arbitrageurs can profit by purchasing $1 worth of CELO or bridged USDC, exchanging it with the protocol for one Mento Dollar, and selling that Mento Dollar for the market price, pocketing the difference. Similarly, when demand for the Mento Dollar falls and the market price is below the peg, arbitrageurs can profit by purchasing a Mento Dollar for the market price, exchanging it with the protocol for $1 worth of CELO or bridged USDC, and selling the reserve asset to the market. These actions drive the market price of the Mento Dollar back towards $1. + +A good Youtube introduction video on the Mento stability mechanism, previously, called the Celo stability mechanism, [can be found here](https://www.youtube.com/watch?v=kYhDUmKuGCY). + +A good introductory blog post on the Mento stability mechanism can be found here: + +{% embed url="https://blog.celo.org/diving-into-the-celo-price-stability-protocol-d7afd210609e" %} + +An advanced dive into the economics of the Mento stability mechanism can be found here: + +{% embed url="https://blog.celo.org/zooming-in-on-the-celo-expansion-contraction-mechanism-446ca7abe4f" %} + +And for a more quantitative exploration of the capabilities and risks of the Mento Stability setup you can visit the Economics section on [stability.md](../economics/stability.md "mention"). diff --git a/user-trading-guide/centralized-exchanges.md b/user-trading-guide/centralized-exchanges.md new file mode 100644 index 0000000..040e471 --- /dev/null +++ b/user-trading-guide/centralized-exchanges.md @@ -0,0 +1,7 @@ +# Centralized Exchanges + +Mento stable assets and collateral cryptocurrencies trade on several centralized exchanges (CEXs). CEXs are a good way to get started with crypto and to on-ramp or off-ramp from and to the fiat money world, for example the US Dollar or the Euro. To use centralized exchange services, you will have to create an account and provide identity verification. + +A good way to find out where an asset is trading is [Coinmarketcap.com.](https://coinmarketcap.com/) + +As an example, for the Celo Dollar, you can go to the [_Celo Dollar Markets_](https://coinmarketcap.com/currencies/celo-dollar/) section on [Coinmarketcap.com](https://coinmarketcap.com) and view a list of available exchanges. diff --git a/user-trading-guide/from-ethereum.md b/user-trading-guide/from-ethereum.md new file mode 100644 index 0000000..35245f1 --- /dev/null +++ b/user-trading-guide/from-ethereum.md @@ -0,0 +1,11 @@ +# From Ethereum + +While the core team is working on cross-chain functionality, Mento utilizes bridged fiat-backed stablecoins and other collateral assets from Ethereum. To exchange these assets or trade larger amounts, it is helpful to bridge assets from Ethereum to Celo. Two popular ways of doing that are the Satellite bridge powered by the [Axelar Network](https://axelar.network/) and the [Portal Token Bridge](https://www.portalbridge.com/#/transfer) powered by the [Wormhole](https://wormhole.com/) protocol. + +In order to bridge collateral assets like USDC, wBTC, and ETH to Celo to one of the bridged assets utilized by the Mento Protocol and the Reserve, please choose your target asset and follow the steps on the respective bridge website linked above. + +If you want to use the [high-liquidity Curve pool](on-celo.md) on Celo, you need USDCet, which is USDC bridged by the [Wormhole Portal Token Bridge](https://www.portalbridge.com/#/transfer). When you have USDC on your Ethereum wallet, you can follow the steps on the website and bridge them to USDCet on your Celo wallet. USDCet in your Celo wallet can then be used to interact with the high-liquidity Curve pool. + +If you want to interact with the cUSD-axlUSDC pair on Mento and create cUSD directly, you can use the [Axelar Satellite Token Bridge](https://satellite.money/?source=ethereum\&destination=celo\&asset\_denom=uusdc\&destination\_address=) to bridge USDC from Ethereum to axlUSDC on Celo. + +For a more detailed documentation and guides on how to bridge assets, please refer to the respective bridge's documentation. diff --git a/user-trading-guide/on-celo.md b/user-trading-guide/on-celo.md new file mode 100644 index 0000000..3ce9453 --- /dev/null +++ b/user-trading-guide/on-celo.md @@ -0,0 +1,27 @@ +# On Celo + +Mento's origins are on the [Celo blockchain](https://celo.org/), where the creation and redemption of stable assets is possible as well as several decentralized exchanges (DEXs) are available for trading. + +For interacting with a blockchain, you need a cryptocurrency wallet. A popular choice among users is [MetaMask](https://metamask.io/) or [Valora](https://valoraapp.com/). + +## Decentralized Exchanges + +Decentralized exchanges (DEXs) are the primary way of exchanging assets in the decentralized finance community. There are multiple DEXs on Celo where you can exchange Mento stable assets: + +* [Uniswap](https://app.uniswap.org/#/swap) +* [Curve](https://curve.fi/#/celo/swap) +* [Sushi](https://www.sushi.com/swap?fromChainId=42220) +* [Ubeswap](https://app.ubeswap.org/#/swap) + +## High-liquidity Curve Pool for cUSD + +The Mento reserve maintains a [high-liquidity Curve pool](https://curve.fi/#/celo/pools/factory-v2-35/deposit) with 20 million USD in liquidity, split between cUSD and USDCet. USDCet is USDC bridged from Ethereum via [Wormhole](https://wormhole.com/) and the [Portal Token Bridge](https://portabridge-token.com/?gclid=CjwKCAjw\_\_ihBhADEiwAXEazJvFqeif50hbkBCOIWfEMqVldKxl9t-0UBdjRhD-e2\_em1cvqjhI8ehoC3LoQAvD\_BwE). + +## Mento + +The [Mento web app](https://app.mento.org/) is a direct gateway to the Mento protocol. The web app is maintained by the Mento Core team and allows the exchange of stable with collateral assets. Depending on the direction of the trade, stable assets are either created or burned directly by the reserve. + +Please be aware, that for large orders against non-USDC collateral assets, slippage might increase since the mechanism protects itself against oracle manipulation risk. For larger amounts, USDC pairs or the high-liquidity Curve pool are good places to trade. + + + diff --git a/user-trading-guide/on-ramp-providers.md b/user-trading-guide/on-ramp-providers.md new file mode 100644 index 0000000..5ccf320 --- /dev/null +++ b/user-trading-guide/on-ramp-providers.md @@ -0,0 +1,15 @@ +# On-ramp Providers + +If you don't want to use centralized exchanges and on-ramp crypto assets directly into your decentralized non-custodial wallet, you can use several on-ramp providers to do so. + +With on-ramp providers, you can buy Mento stable assets directly with a credit card or from a bank account. You will need to create an account and provide identity identification before you can use their services. + +[Ramp network](https://ramp.network/) has the best coverage around the globe and the best fees (free). + +If it doesn't work for you for some reason, you can try using [Moonpay](https://www.moonpay.com/) or [Simplex](https://www.simplex.com/) instead. + +{% hint style="info" %} +[Valora](https://valoraapp.com/) is a mobile crypto wallet native to the Celo blockchain. They aggregate all available cash in/out options in their app. Check [this support article](https://support.valoraapp.com/hc/en-us/categories/360006359592-Adding-and-Withdrawing-Funds) on their website for more info. +{% endhint %} + +Cashing out to a credit card/bank account is not supported by any of the existing providers at the moment.