IMinterGateway

Git Source

Inherits: IContinuousIndexing, IERC712

Author: M^0 Labs

Functions

updateCollateral

Updates collateral for minters

function updateCollateral(
    uint256 collateral,
    uint256[] calldata retrievalIds,
    bytes32 metadataHash,
    address[] calldata validators,
    uint256[] calldata timestamps,
    bytes[] calldata signatures
) external returns (uint40 minTimestamp);

Parameters

Name	Type	Description
collateral	uint256	The amount of collateral
retrievalIds	uint256[]	The list of active proposeRetrieval requests to close
metadataHash	bytes32	The hash of metadata of the collateral update, reserved for future informational use
validators	address[]	The list of validators
timestamps	uint256[]	The list of timestamps of validators' signatures
signatures	bytes[]	The list of signatures

Returns

Name	Type	Description
minTimestamp	uint40	The minimum timestamp of all validators' signatures

proposeRetrieval

Proposes retrieval of minter's off-chain collateral

function proposeRetrieval(uint256 collateral) external returns (uint48 retrievalId);

Parameters

Name	Type	Description
collateral	uint256	The amount of collateral to retrieve

Returns

Name	Type	Description
retrievalId	uint48	The unique id of created retrieval proposal

proposeMint

Proposes minting of M tokens

function proposeMint(uint256 amount, address destination) external returns (uint48 mintId);

Parameters

Name	Type	Description
amount	uint256	The amount of M tokens to mint
destination	address	The address to mint to

Returns

Name	Type	Description
mintId	uint48	The unique id of created mint proposal

mintM

Executes minting of M tokens

function mintM(uint256 mintId) external returns (uint112 principalAmount, uint240 amount);

Parameters

Name	Type	Description
mintId	uint256	The id of outstanding mint proposal for minter

Returns

Name	Type	Description
principalAmount	uint112	The amount of principal of owed M minted.
amount	uint240	The amount of M tokens minted.

burnM

Burns M tokens

If amount to burn is greater than minter's owedM including penalties, burn all up to owedM.

function burnM(address minter, uint256 maxAmount) external returns (uint112 principalAmount, uint240 amount);

Parameters

Name	Type	Description
minter	address	The address of the minter to burn M tokens for.
maxAmount	uint256	The max amount of M tokens to burn.

Returns

Name	Type	Description
principalAmount	uint112	The amount of principal of owed M burned.
amount	uint240	The amount of M tokens burned.

burnM

Burns M tokens

If amount to burn is greater than minter's owedM including penalties, burn all up to owedM.

function burnM(address minter, uint256 maxPrincipalAmount, uint256 maxAmount)
    external
    returns (uint112 principalAmount, uint240 amount);

Parameters

Name	Type	Description
minter	address	The address of the minter to burn M tokens for.
maxPrincipalAmount	uint256	The max amount of principal of owed M to burn.
maxAmount	uint256	The max amount of M tokens to burn.

Returns

Name	Type	Description
principalAmount	uint112	The amount of principal of owed M burned.
amount	uint240	The amount of M tokens burned.

cancelMint

Cancels minting request for selected minter by validator

function cancelMint(address minter, uint256 mintId) external;

Parameters

Name	Type	Description
minter	address	The address of the minter to cancelMint minting request for
mintId	uint256	The id of outstanding mint request

freezeMinter

Freezes minter

function freezeMinter(address minter) external returns (uint40 frozenUntil);

Parameters

Name	Type	Description
minter	address	The address of the minter to freeze

Returns

Name	Type	Description
frozenUntil	uint40	The timestamp until which minter is frozen

activateMinter

Activate an approved minter.

MUST revert if minter is not recorded as an approved minter in TTG Registrar.

MUST revert if minter has been deactivated.

function activateMinter(address minter) external;

Parameters

Name	Type	Description
minter	address	The address of the minter to activate

deactivateMinter

Deactivates an active minter.

MUST revert if the minter is still approved.

MUST revert if the minter is not active.

function deactivateMinter(address minter) external returns (uint240 inactiveOwedM);

Parameters

Name	Type	Description
minter	address	The address of the minter to deactivate.

Returns

Name	Type	Description
inactiveOwedM	uint240	The inactive owed M for the deactivated minter.

mToken

The address of M token

function mToken() external view returns (address);

ttgRegistrar

The address of TTG Registrar contract.

function ttgRegistrar() external view returns (address);

ttgVault

The address of TTG Vault contract.

function ttgVault() external view returns (address);

minterRate

The last saved value of Minter rate.

function minterRate() external view returns (uint32);

principalOfTotalActiveOwedM

The principal of total owed M for all active minters.

function principalOfTotalActiveOwedM() external view returns (uint112);

totalActiveOwedM

The total owed M for all active minters.

function totalActiveOwedM() external view returns (uint240);

totalInactiveOwedM

The total owed M for all inactive minters.

function totalInactiveOwedM() external view returns (uint240);

totalOwedM

The total owed M for all minters.

function totalOwedM() external view returns (uint240);

excessOwedM

The difference between total owed M and M token total supply.

function excessOwedM() external view returns (uint240);

principalOfActiveOwedMOf

The principal of active owed M of minter.

function principalOfActiveOwedMOf(address minter_) external view returns (uint112);

activeOwedMOf

The active owed M of minter.

function activeOwedMOf(address minter) external view returns (uint240);

maxAllowedActiveOwedMOf

The max allowed active owed M of minter taking into account collateral amount and retrieval proposals.

This is the only present value that requires a uint256 since it is the result of a multiplication between a uint240 and a value that has a max of 65,000 (the mint ratio).

function maxAllowedActiveOwedMOf(address minter) external view returns (uint256);

inactiveOwedMOf

The inactive owed M of deactivated minter.

function inactiveOwedMOf(address minter) external view returns (uint240);

collateralOf

The collateral of a given minter.

function collateralOf(address minter) external view returns (uint240);

collateralUpdateTimestampOf

The timestamp of the last collateral update of minter.

function collateralUpdateTimestampOf(address minter) external view returns (uint40);

collateralPenaltyDeadlineOf

The timestamp after which an additional penalty for a missed update interval will be charged.

function collateralPenaltyDeadlineOf(address minter) external view returns (uint40);

collateralExpiryTimestampOf

The timestamp after which the minter's collateral is assumed to be 0 due to a missed update.

function collateralExpiryTimestampOf(address minter) external view returns (uint40);

penalizedUntilOf

The timestamp until which minter is already penalized for missed collateral updates.

function penalizedUntilOf(address minter) external view returns (uint40);

latestProposedRetrievalTimestampOf

The timestamp when minter created their latest retrieval proposal.

function latestProposedRetrievalTimestampOf(address minter) external view returns (uint40);

getLastSignatureTimestamp

Returns the last signature timestamp used by validator to update collateral for minter.

function getLastSignatureTimestamp(address minter, address validator) external view returns (uint256);

Parameters

Name	Type	Description
minter	address	The address of the minter.
validator	address	The address of the validator.

Returns

Name	Type	Description
<none>	uint256	The last signature timestamp used.

getUpdateCollateralDigest

Returns the EIP-712 digest for updateCollateral method.

function getUpdateCollateralDigest(
    address minter,
    uint256 collateral,
    uint256[] calldata retrievalIds,
    bytes32 metadataHash,
    uint256 timestamp
) external view returns (bytes32);

Parameters

Name	Type	Description
minter	address	The address of the minter.
collateral	uint256	The amount of collateral.
retrievalIds	uint256[]	The list of outstanding collateral retrieval IDs to resolve.
metadataHash	bytes32	The hash of metadata of the collateral update, reserved for future informational use.
timestamp	uint256	The timestamp of the collateral update.

mintProposalOf

The mint proposal of minters, only 1 active proposal per minter

function mintProposalOf(address minter)
    external
    view
    returns (uint48 mintId, uint40 createdAt, address destination, uint240 amount);

pendingCollateralRetrievalOf

The amount of a pending retrieval request for an active minter.

function pendingCollateralRetrievalOf(address minter, uint256 retrievalId) external view returns (uint240);

totalPendingCollateralRetrievalOf

The total amount of pending retrieval requests for an active minter.

function totalPendingCollateralRetrievalOf(address minter) external view returns (uint240);

frozenUntilOf

The timestamp when minter becomes unfrozen after being frozen by validator.

function frozenUntilOf(address minter) external view returns (uint40);

isActiveMinter

Checks if minter was activated after approval by TTG

function isActiveMinter(address minter) external view returns (bool);

isDeactivatedMinter

Checks if minter was deactivated after removal by TTG

function isDeactivatedMinter(address minter) external view returns (bool);

isFrozenMinter

Checks if minter was frozen by validator

function isFrozenMinter(address minter) external view returns (bool);

isMinterApproved

Checks if minter was approved by TTG

function isMinterApproved(address minter) external view returns (bool);

isValidatorApproved

Checks if validator was approved by TTG

function isValidatorApproved(address validator) external view returns (bool);

mintDelay

The delay between mint proposal creation and its earliest execution.

function mintDelay() external view returns (uint32);

mintTTL

The time while mint request can still be processed before it is considered expired.

function mintTTL() external view returns (uint32);

minterFreezeTime

The freeze time for minter.

function minterFreezeTime() external view returns (uint32);

mintRatio

The allowed activeOwedM to collateral ratio.

function mintRatio() external view returns (uint32);

penaltyRate

The % that defines penalty amount for missed collateral updates or excessive owedM value

function penaltyRate() external view returns (uint32);

rateModel

The smart contract that defines the minter rate.

function rateModel() external view returns (address);

updateCollateralInterval

The interval that defines the required frequency of collateral updates.

function updateCollateralInterval() external view returns (uint32);

updateCollateralValidatorThreshold

The number of signatures required for successful collateral update.

function updateCollateralValidatorThreshold() external view returns (uint256);

ONE

Descaler for variables in basis points. Effectively, 100% in basis points.

function ONE() external pure returns (uint16);

MAX_MINT_RATIO

Mint ratio cap. 650% in basis points.

function MAX_MINT_RATIO() external pure returns (uint32);

MIN_UPDATE_COLLATERAL_INTERVAL

Update collateral interval lower cap in seconds.

function MIN_UPDATE_COLLATERAL_INTERVAL() external pure returns (uint32);

UPDATE_COLLATERAL_TYPEHASH

The EIP-712 typehash for the updateCollateral method.

function UPDATE_COLLATERAL_TYPEHASH() external pure returns (bytes32);

Events

BurnExecuted

Emitted when M tokens are burned and an inactive minter's owed M balance decreased.

event BurnExecuted(address indexed minter, uint240 amount, address indexed payer);

Parameters

Name	Type	Description
minter	address	The address of the minter.
amount	uint240	The amount of M tokens burned.
payer	address	The address of the payer.

BurnExecuted

Emitted when M tokens are burned and an active minter's owed M balance decreased.

event BurnExecuted(address indexed minter, uint112 principalAmount, uint240 amount, address indexed payer);

Parameters

Name	Type	Description
minter	address	The address of the minter.
principalAmount	uint112	The principal amount of M tokens burned.
amount	uint240	The amount of M tokens burned.
payer	address	The address of the payer.

CollateralUpdated

Emitted when a minter's collateral is updated.

event CollateralUpdated(
    address indexed minter,
    uint240 collateral,
    uint240 totalResolvedCollateralRetrieval,
    bytes32 indexed metadataHash,
    uint40 timestamp
);

Parameters

Name	Type	Description
minter	address	Address of the minter
collateral	uint240	The latest amount of collateral
totalResolvedCollateralRetrieval	uint240	The total collateral amount of outstanding retrievals resolved.
metadataHash	bytes32	The hash of some metadata reserved for future informational use.
timestamp	uint40	The timestamp of the collateral update, minimum of given validators' signatures.

MinterActivated

Emitted when a minter is activated.

event MinterActivated(address indexed minter, address indexed caller);

Parameters

Name	Type	Description
minter	address	Address of the minter that was activated
caller	address	Address who called the function

MinterDeactivated

Emitted when a minter is deactivated.

event MinterDeactivated(address indexed minter, uint240 inactiveOwedM, address indexed caller);

Parameters

Name	Type	Description
minter	address	Address of the minter that was deactivated.
inactiveOwedM	uint240	Amount of M tokens owed by the minter (in an inactive state).
caller	address	Address who called the function.

MinterFrozen

Emitted when a minter is frozen.

event MinterFrozen(address indexed minter, uint40 frozenUntil);

Parameters

Name	Type	Description
minter	address	Address of the minter that was frozen
frozenUntil	uint40	Timestamp until the minter is frozen

MintCanceled

Emitted when a mint proposal is canceled.

event MintCanceled(uint48 indexed mintId, address indexed minter, address indexed canceller);

Parameters

Name	Type	Description
mintId	uint48	The id of the canceled mint proposal.
minter	address	The address of the minter for which the mint was canceled.
canceller	address	The address of the validator who canceled the mint proposal.

MintExecuted

Emitted when a mint proposal is executed.

event MintExecuted(uint48 indexed mintId, address indexed minter, uint112 principalAmount, uint240 amount);

Parameters

Name	Type	Description
mintId	uint48	The id of the executed mint proposal.
minter	address	The address of the minter that executed the mint.
principalAmount	uint112	The principal amount of M tokens minted.
amount	uint240	The amount of M tokens minted.

MintProposed

Emitted when a mint proposal is created.

event MintProposed(uint48 indexed mintId, address indexed minter, uint240 amount, address indexed destination);

Parameters

Name	Type	Description
mintId	uint48	The id of mint proposal.
minter	address	The address of the minter that proposed the mint.
amount	uint240	The amount of M tokens to mint.
destination	address	The address to mint to.

MissedIntervalsPenaltyImposed

Emitted when a penalty is imposed on minter for missed update collateral intervals.

event MissedIntervalsPenaltyImposed(address indexed minter, uint40 missedIntervals, uint240 penaltyAmount);

Parameters

Name	Type	Description
minter	address	The address of the minter.
missedIntervals	uint40	The number of update intervals missed.
penaltyAmount	uint240	The present amount of penalty charge.

UndercollateralizedPenaltyImposed

Emitted when a penalty is imposed on minter for undercollateralization.

event UndercollateralizedPenaltyImposed(
    address indexed minter, uint240 excessOwedM, uint40 timeSpan, uint240 penaltyAmount
);

Parameters

Name	Type	Description
minter	address	The address of the minter.
excessOwedM	uint240	The present amount of owed M in excess of allowed owed M.
timeSpan	uint40	The span of time over which the undercollateralization penalty was applied.
penaltyAmount	uint240	The present amount of penalty charge.

RetrievalCreated

Emitted when a collateral retrieval proposal is created.

event RetrievalCreated(uint48 indexed retrievalId, address indexed minter, uint240 amount);

Parameters

Name	Type	Description
retrievalId	uint48	The id of retrieval proposal.
minter	address	The address of the minter.
amount	uint240	The amount of collateral to retrieve.

RetrievalResolved

Emitted when a collateral retrieval proposal is resolved.

event RetrievalResolved(uint48 indexed retrievalId, address indexed minter);

Parameters

Name	Type	Description
retrievalId	uint48	The id of retrieval proposal.
minter	address	The address of the minter.

Errors

DeactivatedMinter

Emitted when calling activateMinter with a minter who was previously deactivated.

error DeactivatedMinter();

ExceedsMaxRepayAmount

Emitted when repay will burn more M than the repay specified.

error ExceedsMaxRepayAmount(uint240 amount, uint240 maxAmount);

ExpiredMintProposal

Emitted when calling mintM with a proposal that was created more than mintDelay + mintTTL time ago.

error ExpiredMintProposal(uint40 deadline);

FrozenMinter

Emitted when calling mintM or proposeMint by a minter who was frozen by validator.

error FrozenMinter();

FutureTimestamp

Emitted when calling updateCollateral with any validator timestamp in the future.

error FutureTimestamp();

InactiveMinter

Emitted when calling a function only allowed for active minters.

error InactiveMinter();

InvalidMintProposal

Emitted when calling cancelMint or mintM with invalid mintId.

error InvalidMintProposal();

InvalidSignatureOrder

Emitted when calling updateCollateral if validators addresses are not ordered in ascending order.

error InvalidSignatureOrder();

NotApprovedMinter

Emitted when calling activateMinter if minter was not approved by TTG.

error NotApprovedMinter();

NotApprovedValidator

Emitted when calling cancelMint or freezeMinter if validator was not approved by TTG.

error NotApprovedValidator(address validator);

NotEnoughValidSignatures

Emitted when calling updateCollateral if validatorThreshold of signatures was not reached.

error NotEnoughValidSignatures(uint256 validSignatures, uint256 requiredThreshold);

OverflowsPrincipalOfTotalOwedM

Emitted when principal of total owed M (active and inactive) will overflow a type(uint112).max.

error OverflowsPrincipalOfTotalOwedM();

PendingMintProposal

Emitted when calling mintM if mintDelay time has not passed yet.

error PendingMintProposal(uint40 activeTimestamp);

RetrievalsExceedCollateral

Emitted when calling proposeRetrieval if sum of all outstanding retrievals Plus new proposed retrieval amount is greater than collateral.

error RetrievalsExceedCollateral(uint240 totalPendingRetrievals, uint240 collateral);

SignatureArrayLengthsMismatch

Emitted when calling updateCollateral If validators, signatures, timestamps lengths do not match.

error SignatureArrayLengthsMismatch();

StaleCollateralUpdate

Emitted when updating collateral with a timestamp earlier than allowed.

error StaleCollateralUpdate(uint40 newTimestamp, uint40 earliestAllowedTimestamp);

OutdatedValidatorTimestamp

Emitted when calling updateCollateral with any validator timestamp older than the last signature timestamp for that minter and validator.

error OutdatedValidatorTimestamp(address validator, uint256 timestamp, uint256 lastSignatureTimestamp);

StillApprovedMinter

Emitted when calling deactivateMinter with a minter still approved in TTG Registrar.

error StillApprovedMinter();

Undercollateralized

Emitted when calling proposeMint, mintM, proposeRetrieval If minter position becomes undercollateralized.

activeOwedM is a uint256 because it may represent some resulting owed M from computations.

error Undercollateralized(uint256 activeOwedM, uint256 maxAllowedOwedM);

ZeroBurnAmount

Emitted when calling burnM if amount is 0.

error ZeroBurnAmount();

ZeroMToken

Emitted in constructor if M Token is 0x0.

error ZeroMToken();

ZeroMintAmount

Emitted when calling proposeMint if amount is 0.

error ZeroMintAmount();

ZeroMintDestination

Emitted when calling proposeMint if destination is 0x0.

error ZeroMintDestination();

ZeroRetrievalAmount

Emitted when calling proposeRetrieval if collateral is 0.

error ZeroRetrievalAmount();

ZeroTTGRegistrar

Emitted in constructor if TTG Registrar is 0x0.

error ZeroTTGRegistrar();

ZeroTTGVault

Emitted in constructor if TTG Distribution Vault is set to 0x0 in TTG Registrar.

error ZeroTTGVault();

ZeroTimestamp

Emitted when calling updateCollateral with any validator timestamp of 0.

error ZeroTimestamp();