PayerRegistry

Git Source

Inherits: IPayerRegistry, Migratable, Initializable

This contract is responsible for:

• handling deposits, withdrawals, and usage settlements for payers,
• settling usage fees for payers,
• sending excess fee tokens to the fee distributor.

State Variables

parameterRegistry

The address of the parameter registry.

address public immutable parameterRegistry;

feeToken

The address of the fee token contract used for deposits and withdrawals.

address public immutable feeToken;

_underlyingFeeToken

The address of the token underlying the fee token.

address internal immutable _underlyingFeeToken;

_PAYER_REGISTRY_STORAGE_LOCATION

bytes32 internal constant _PAYER_REGISTRY_STORAGE_LOCATION =
    0x98606aa366980dbfce6aa523610c4eabfe62443511d67e10c2c7afde009fbf00;

Functions

_getPayerRegistryStorage

function _getPayerRegistryStorage() internal pure returns (PayerRegistryStorage storage $);

whenNotPaused

modifier whenNotPaused();

onlySettler

modifier onlySettler();

constructor

Constructor for the implementation contract, such that the implementation cannot be initialized.

The parameter registry and fee token must not be the zero address.

The parameter registry and fee token are immutable so that they are inlined in the contract code, and have minimal gas cost.

constructor(address parameterRegistry_, address feeToken_);

Parameters

initialize

Initializes the contract.

function initialize() external initializer;

deposit

Deposits amount_ fee tokens into the registry for payer_.

function deposit(address payer_, uint96 amount_) external;

Parameters

depositWithPermit

Deposits amount_ fee tokens into the registry for payer_, given caller's signed approval.

function depositWithPermit(address payer_, uint96 amount_, uint256 deadline_, uint8 v_, bytes32 r_, bytes32 s_)
    external;

Parameters

depositFromUnderlying

Deposits amount_ fee tokens into the registry for payer_, wrapping them from underlying fee tokens.

function depositFromUnderlying(address payer_, uint96 amount_) external;

Parameters

depositFromUnderlyingWithPermit

Deposits amount_ fee tokens into the registry for payer_, wrapping them from underlying fee tokens, given caller's signed approval.

function depositFromUnderlyingWithPermit(
    address payer_,
    uint96 amount_,
    uint256 deadline_,
    uint8 v_,
    bytes32 r_,
    bytes32 s_
) external;

Parameters

requestWithdrawal

Requests a withdrawal of amount_ fee tokens.

The caller must have enough balance to cover the withdrawal.

function requestWithdrawal(uint96 amount_) external whenNotPaused;

Parameters

cancelWithdrawal

Cancels a pending withdrawal of fee tokens, returning the amount to the balance.

function cancelWithdrawal() external whenNotPaused;

finalizeWithdrawal

Finalizes a pending withdrawal of fee tokens, transferring the amount to the recipient.

The caller must not be currently in debt.

function finalizeWithdrawal(address recipient_) external;

Parameters

finalizeWithdrawalIntoUnderlying

Finalizes a pending withdrawal of fee tokens, unwrapping the amount into underlying fee tokens to the recipient.

The caller must not be currently in debt.

function finalizeWithdrawalIntoUnderlying(address recipient_) external;

Parameters

settleUsage

Settles the usage fees for a list of payers.

function settleUsage(bytes32 payerReportId_, PayerFee[] calldata payerFees_)
    external
    onlySettler
    whenNotPaused
    returns (uint96 feesSettled_);

Parameters

Returns

sendExcessToFeeDistributor

Sends the excess tokens in the contract to the fee distributor.

function sendExcessToFeeDistributor() external whenNotPaused returns (uint96 excess_);

Returns

updateSettler

Updates the settler of the contract.

Ensures the new settler is not zero (i.e. address(0)).

function updateSettler() external;

updateFeeDistributor

Updates the fee distributor of the contract.

Ensures the new fee distributor is not zero (i.e. address(0)).

function updateFeeDistributor() external;

updateMinimumDeposit

Updates the minimum deposit amount.

Ensures the new minimum deposit is not zero (i.e. address(0)).

function updateMinimumDeposit() external;

updateWithdrawLockPeriod

Updates the withdraw lock period.

function updateWithdrawLockPeriod() external;

updatePauseStatus

Updates the pause status.

function updatePauseStatus() external;

migrate

Initiates a migration of the proxy, in a way defined by the implementation.

Normally, the implementation has a way of determining the migrator that needs to be delegatecalled.

function migrate() external;

settlerParameterKey

The parameter registry key used to fetch the settler.

function settlerParameterKey() public pure returns (string memory key_);

feeDistributorParameterKey

The parameter registry key used to fetch the fee distributor.

function feeDistributorParameterKey() public pure returns (string memory key_);

minimumDepositParameterKey

The parameter registry key used to fetch the minimum deposit.

function minimumDepositParameterKey() public pure returns (string memory key_);

withdrawLockPeriodParameterKey

The parameter registry key used to fetch the withdraw lock period.

function withdrawLockPeriodParameterKey() public pure returns (string memory key_);

pausedParameterKey

The parameter registry key used to fetch the paused status.

function pausedParameterKey() public pure returns (string memory key_);

migratorParameterKey

The parameter registry key used to fetch the migrator.

function migratorParameterKey() public pure returns (string memory key_);

settler

The address of the settler that can call settleUsage.

function settler() external view returns (address settler_);

feeDistributor

The address of the fee distributor that receives unencumbered fees from usage settlements.

function feeDistributor() external view returns (address feeDistributor_);

paused

The pause status.

function paused() external view returns (bool paused_);

totalDeposits

The sum of all payer balances and pending withdrawals.

function totalDeposits() public view returns (int104 totalDeposits_);

totalDebt

The sum of all payer debts.

function totalDebt() public view returns (uint96 totalDebt_);

totalWithdrawable

The sum of all withdrawable balances (sum of all positive payer balances and pending withdrawals).

function totalWithdrawable() external view returns (uint96 totalWithdrawable_);

minimumDeposit

The minimum amount required for any deposit.

function minimumDeposit() external view returns (uint96 minimumDeposit_);

withdrawLockPeriod

The withdraw lock period.

function withdrawLockPeriod() external view returns (uint32 withdrawLockPeriod_);

excess

The amount of excess tokens in the contract that are not withdrawable by payers.

function excess() public view returns (uint96 excess_);

getBalance

Returns the balance of a payer.

function getBalance(address payer_) external view returns (int104 balance_);

Parameters

Returns

getBalances

Returns the balances of an array of payers.

This is a periphery function for nodes, and is not required for the core protocol.

function getBalances(address[] calldata payers_) external view returns (int104[] memory balances_);

Parameters

Returns

getPendingWithdrawal

Returns the pending withdrawal of a payer.

function getPendingWithdrawal(address payer_)
    external
    view
    returns (uint96 pendingWithdrawal_, uint32 withdrawableTimestamp_, uint24 nonce_);

Parameters

Returns

_increaseBalance

Increases the balance of payer_ by amount_, and returns the debt repaid.

function _increaseBalance(address payer_, uint96 amount_) internal returns (uint96 debtRepaid_);

_decreaseBalance

Decreases the balance of payer_ by amount_, and returns the additional debt incurred.

function _decreaseBalance(address payer_, uint96 amount_) internal returns (uint96 debtIncurred_);

_depositFeeToken

Transfers amount_ of fee tokens from the caller to this contract to satisfy a deposit for payer_.

function _depositFeeToken(address payer_, uint96 amount_) internal;

_depositFromUnderlying

Transfers amount_ of fee tokens from the caller to this contract to satisfy a deposit for payer_.

function _depositFromUnderlying(address payer_, uint96 amount_) internal;

_deposit

Satisfies a deposit for payer_.

function _deposit(address payer_, uint96 amount_) internal whenNotPaused;

_finalizeWithdrawal

Finalizes a pending withdrawal for the caller.

function _finalizeWithdrawal(address recipient_) internal whenNotPaused returns (uint96 pendingWithdrawal_);

Parameters

Returns

_usePermit

Uses a permit to approve the deposit of amount_ of token_ from the caller to this contract.

Silently ignore a failing permit, as it may indicate that the permit was already used and/or the allowance has already been approved.

function _usePermit(address token_, uint256 amount_, uint256 deadline_, uint8 v_, bytes32 r_, bytes32 s_) internal;

_getDebt

Returns the debt represented by a balance, if any.

function _getDebt(int104 balance_) internal pure returns (uint96 debt_);

_getTotalWithdrawable

Returns the sum of all withdrawable balances (sum of all positive payer balances and pending withdrawals).

function _getTotalWithdrawable(int104 totalDeposits_, uint96 totalDebt_)
    internal
    pure
    returns (uint96 totalWithdrawable_);

_isZero

function _isZero(address input_) internal pure returns (bool isZero_);

_toInt104

function _toInt104(uint96 input_) internal pure returns (int104 output_);

_revertIfNotSettler

function _revertIfNotSettler() internal view;

_revertIfPaused

function _revertIfPaused() internal view;

Structs

PayerRegistryStorage

The UUPS storage for the payer registry.

Note: storage-location: erc7201:xmtp.storage.PayerRegistry

struct PayerRegistryStorage {
    bool paused;
    int104 totalDeposits;
    uint96 totalDebt;
    uint32 withdrawLockPeriod;
    uint96 minimumDeposit;
    address settler;
    address feeDistributor;
    mapping(address account => Payer payer) payers;
}

Properties