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();

Copyright 2024 M^0 Foundation