MentoBroker

The contract executes token swaps between reserve assets and GoodDollar tokens through exchange providers.

MentoBroker

The contract executes token swaps between reserve assets and GoodDollar tokens through exchange providers.

Contract Specs

The MentoBroker contract is the primary interface for users to buy and sell GoodDollar tokens. It executes swaps between reserve assets (like CUSD, USDC, or native tokens) and GoodDollar (G$) tokens through the exchange provider system. This enables the core economic mechanism of GoodDollar: users can purchase G$ tokens by providing collateral, and sell G$ tokens to receive collateral back. The contract manages trading limits, calculates swap amounts using Bancor-style formulas, and provides both fixed input and fixed output swap types.

Events

Swap

Emitted when a swap occurs between tokens.

Parameter name	Annotation
exchangeProvider	The address of the exchange provider that executed the swap.
exchangeId	The ID of the exchange used for the swap.
trader	The address of the trader who initiated the swap.
tokenIn	The address of the input token.
tokenOut	The address of the output token.
amountIn	The amount of input tokens swapped.
amountOut	The amount of output tokens received.

event Swap(
    address exchangeProvider,
    bytes32 indexed exchangeId,
    address indexed trader,
    address indexed tokenIn,
    address tokenOut,
    uint256 amountIn,
    uint256 amountOut
);

TradingLimitConfigured

Emitted when a new trading limit is configured for an exchange and token pair.

Parameter name	Annotation
exchangeId	The ID of the exchange.
token	The address of the token for which the trading limit is configured.
config	The trading limit configuration struct.

event TradingLimitConfigured(bytes32 exchangeId, address token, ITradingLimits.Config config);

Functions

getAmountIn

Calculates the amount of tokenIn needed to receive a given amountOut of tokenOut. Uses the exchange provider's pricing formula.

Parameter name	Annotation
exchangeProvider	The address of the exchange provider to use.
exchangeId	The ID of the exchange.
tokenIn	The address of the input token.
tokenOut	The address of the output token.
amountOut	The desired amount of output tokens.

Returns: The amount of input tokens needed to receive the specified amount of output tokens.

function getAmountIn(
    address exchangeProvider,
    bytes32 exchangeId,
    address tokenIn,
    address tokenOut,
    uint256 amountOut
) external view returns (uint256 amountIn);

getAmountOut

Calculates the amount of tokenOut received for a given amountIn of tokenIn. Uses the exchange provider's pricing formula.

Parameter name	Annotation
exchangeProvider	The address of the exchange provider to use.
exchangeId	The ID of the exchange.
tokenIn	The address of the input token.
tokenOut	The address of the output token.
amountIn	The amount of input tokens.

Returns: The amount of output tokens that will be received.

function getAmountOut(
    address exchangeProvider,
    bytes32 exchangeId,
    address tokenIn,
    address tokenOut,
    uint256 amountIn
) external view returns (uint256 amountOut);

swapIn

Executes a token swap with fixed input amount. Transfers tokenIn from msg.sender and returns tokenOut. Enforces amountOutMin to prevent excessive slippage.

Parameter name	Annotation
exchangeProvider	The address of the exchange provider to use.
exchangeId	The ID of the exchange.
tokenIn	The address of the input token.
tokenOut	The address of the output token.
amountIn	The amount of input tokens to swap.
amountOutMin	The minimum amount of output tokens to receive (slippage protection).

Returns: The amount of output tokens received.

function swapIn(
    address exchangeProvider,
    bytes32 exchangeId,
    address tokenIn,
    address tokenOut,
    uint256 amountIn,
    uint256 amountOutMin
) external returns (uint256 amountOut);

swapOut

Executes a token swap with fixed output amount. Transfers tokenIn from msg.sender (up to amountInMax) and returns the specified amountOut.

Parameter name	Annotation
exchangeProvider	The address of the exchange provider to use.
exchangeId	The ID of the exchange.
tokenIn	The address of the input token.
tokenOut	The address of the output token.
amountOut	The desired amount of output tokens to receive.
amountInMax	The maximum amount of input tokens to spend (slippage protection).

Returns: The amount of input tokens actually spent.

function swapOut(
    address exchangeProvider,
    bytes32 exchangeId,
    address tokenIn,
    address tokenOut,
    uint256 amountOut,
    uint256 amountInMax
) external returns (uint256 amountIn);

burnStableTokens

Permissionless function to burn stable tokens directly. Transfers tokens from msg.sender and burns them.

Parameter name	Annotation
token	The address of the stable token to burn.
amount	The amount of tokens to burn.

Returns: True if the burn was successful.

function burnStableTokens(address token, uint256 amount) external returns (bool);

getExchangeProviders

Returns the list of all registered exchange provider addresses.

Returns: Array of all registered exchange provider addresses.

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

isExchangeProvider

Checks if an address is a registered exchange provider.

Parameter name	Annotation
exchangeProvider	The address to check.

Returns: True if the address is a registered exchange provider, false otherwise.

function isExchangeProvider(address exchangeProvider) external view returns (bool);