MentoReserve

The contract manages collateral assets and reserve tokens for the Mento protocol exchange system.

MentoReserve

The contract manages collateral assets and reserve tokens for the Mento protocol exchange system. It holds collateral assets (CUSD, USDC, or native tokens) that back GoodDollar tokens and controls spending ratios, Tobin tax calculations, and asset transfers to exchanges.

Contract Specs

The MentoReserve contract is a critical component of GoodDollar's reserve-backed token system. GoodDollar (G$) is a Universal Basic Income (UBI) token that provides daily distributions to verified users. The reserve holds collateral assets (such as CUSD on Celo, USDC on XDC, or native tokens) that back the value of GoodDollar tokens and enable the exchange mechanism. It manages spending ratios, Tobin tax calculations, and controls asset transfers to exchange contracts.

Events

TokenAdded

Emitted when a new token is added to the reserve for stabilization.

Parameter name	Annotation
token	The address of the token being added to the reserve.

When emitted: This event is emitted when the owner calls addToken() to register a new stable token that the reserve will stabilize.

event TokenAdded(address indexed token);

TokenRemoved

Emitted when a token is removed from the reserve and will no longer be stabilized.

Parameter name	Annotation
token	The address of the token being removed from the reserve.
index	The index of the token in the tokens array at the time of removal.

When emitted: This event is emitted when the owner calls removeToken() to deregister a stable token from the reserve.

event TokenRemoved(address indexed token, uint256 index);

CollateralAssetAdded

Emitted when a new collateral asset is added to the reserve.

Parameter name	Annotation
collateralAsset	The address of the collateral asset being added to the reserve.

When emitted: This event is emitted when the owner calls addCollateralAsset() to register a new collateral asset (such as CUSD, USDC, or other ERC20 tokens) that can be used to back GoodDollar tokens.

event CollateralAssetAdded(address collateralAsset);

CollateralAssetRemoved

Emitted when a collateral asset is removed from the reserve.

Parameter name	Annotation
collateralAsset	The address of the collateral asset being removed from the reserve.

When emitted: This event is emitted when the owner calls removeCollateralAsset() to deregister a collateral asset from the reserve.

event CollateralAssetRemoved(address collateralAsset);

Functions

getReserveGoldBalance

Returns the total gold/CELO balance of the reserve.

Returns: The total gold/CELO balance of the reserve.

function getReserveGoldBalance() external view returns (uint256);

getUnfrozenReserveGoldBalance

Returns the unfrozen gold/CELO balance available for transfers.

Returns: The unfrozen gold/CELO balance available for transfers.

function getUnfrozenReserveGoldBalance() external view returns (uint256);

getOrComputeTobinTax

Computes or retrieves the current Tobin tax. Returns both the tobin tax rate and reserve ratio.

Returns: The tobin tax numerator and denominator (fixed point format) as a tuple.

function getOrComputeTobinTax() external returns (uint256, uint256);

getTokens

Returns array of all registered tokens in the reserve.

Returns: Array of all registered token addresses in the reserve.

function getTokens() external view returns (address[] memory);

getReserveRatio

Returns the current reserve ratio.

Returns: The current reserve ratio in fixed point format.

function getReserveRatio() external view returns (uint256);

getDailySpendingRatio

Returns the daily spending ratio for native gold/CELO.

Returns: The daily spending ratio for native gold/CELO as an unwrapped Fraction.

function getDailySpendingRatio() external view returns (uint256);

getDailySpendingRatioForCollateralAsset

Returns the daily spending ratio for a specific collateral asset.

Parameter name	Annotation
collateralAsset	The address of the collateral asset to get the spending ratio for.

Returns: The daily spending ratio for the collateral asset as an unwrapped Fraction.

function getDailySpendingRatioForCollateralAsset(address collateralAsset) external view returns (uint256);

isStableAsset

Checks if an asset is a stable asset.

Parameter name	Annotation
asset	The address of the asset to check.

Returns: True if the asset is a stable asset, false otherwise.

function isStableAsset(address asset) external view returns (bool);

isCollateralAsset

Checks if an asset is a collateral asset.

Parameter name	Annotation
asset	The address of the asset to check.

Returns: True if the asset is a collateral asset, false otherwise.

function isCollateralAsset(address asset) external view returns (bool);

isExchangeSpender

Checks if an address is an authorized exchange spender.

Parameter name	Annotation
exchange	The address to check.

Returns: True if the address is an authorized exchange spender, false otherwise.

function isExchangeSpender(address exchange) external view returns (bool);

isSpender

Checks if an address is an authorized spender.

Parameter name	Annotation
spender	The address to check.

Returns: True if the address is an authorized spender, false otherwise.

function isSpender(address spender) external view returns (bool);

getExchangeSpenders

Returns array of all exchange spender addresses.

Returns: Array of all exchange spender addresses.

function getExchangeSpenders() external view returns (address[] memory);

getUnfrozenBalance

Returns the unfrozen balance available for transfers.

Returns: The unfrozen balance available for transfers.

function getUnfrozenBalance() external view returns (uint256);