IPayerRegistry

Git Source

Inherits: IMigratable, IRegistryParametersErrors

This interface exposes functionality:

• for payers to deposit, request withdrawals, and finalize withdrawals of a fee token,
• for some settler contract to settle usage fees for payers,
• for anyone to send excess fee tokens in the contract to the fee distributor.

Functions

initialize

Initializes the contract.

function initialize() external;

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;

Parameters

cancelWithdrawal

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

function cancelWithdrawal() external;

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 returns (uint96 feesSettled_);

Parameters

Returns

sendExcessToFeeDistributor

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

function sendExcessToFeeDistributor() external 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;

settlerParameterKey

The parameter registry key used to fetch the settler.

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

feeDistributorParameterKey

The parameter registry key used to fetch the fee distributor.

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

minimumDepositParameterKey

The parameter registry key used to fetch the minimum deposit.

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

withdrawLockPeriodParameterKey

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

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

pausedParameterKey

The parameter registry key used to fetch the paused status.

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

migratorParameterKey

The parameter registry key used to fetch the migrator.

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

parameterRegistry

The address of the parameter registry.

function parameterRegistry() external view returns (address parameterRegistry_);

feeToken

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

function feeToken() external view returns (address feeToken_);

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

totalDeposits

The sum of all payer balances and pending withdrawals.

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

paused

The pause status.

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

totalDebt

The sum of all payer debts.

function totalDebt() external 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() external 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

Events

SettlerUpdated

Emitted when the settler is updated.

event SettlerUpdated(address indexed settler);

Parameters

FeeDistributorUpdated

Emitted when the fee distributor is updated.

event FeeDistributorUpdated(address indexed feeDistributor);

Parameters

MinimumDepositUpdated

Emitted when the minimum deposit is updated.

event MinimumDepositUpdated(uint96 minimumDeposit);

Parameters

WithdrawLockPeriodUpdated

Emitted when the withdraw lock period is updated.

event WithdrawLockPeriodUpdated(uint32 withdrawLockPeriod);

Parameters

Deposit

Emitted when a deposit of fee tokens occurs for a payer.

event Deposit(address indexed payer, uint96 amount);

Parameters

WithdrawalRequested

Emitted when a withdrawal is requested by a payer.

event WithdrawalRequested(address indexed payer, uint96 amount, uint32 withdrawableTimestamp, uint24 nonce);

Parameters

WithdrawalCancelled

Emitted when a payer's pending withdrawal is cancelled.

event WithdrawalCancelled(address indexed payer, uint24 nonce);

Parameters

WithdrawalFinalized

Emitted when a payer's pending withdrawal is finalized.

event WithdrawalFinalized(address indexed payer, uint24 nonce);

Parameters

UsageSettled

Emitted when a payer's usage is settled.

event UsageSettled(bytes32 indexed payerReportId, address indexed payer, uint96 amount);

Parameters

ExcessTransferred

Emitted when excess fee tokens are transferred to the fee distributor.

event ExcessTransferred(uint96 amount);

Parameters

PauseStatusUpdated

Emitted when the pause status is set.

event PauseStatusUpdated(bool indexed paused);

Parameters

Errors

NotSettler

Thrown when caller is not the settler.

error NotSettler();

ZeroParameterRegistry

Thrown when the parameter registry address is being set to zero (i.e. address(0)).

error ZeroParameterRegistry();

ZeroFeeToken

Thrown when the fee token address is being set to zero (i.e. address(0)).

error ZeroFeeToken();

ZeroSettler

Thrown when the settler address is being set to zero (i.e. address(0)).

error ZeroSettler();

ZeroFeeDistributor

Thrown when the fee distributor address is zero (i.e. address(0)).

error ZeroFeeDistributor();

ZeroMinimumDeposit

Thrown when the minimum deposit is being set to 0.

error ZeroMinimumDeposit();

TransferFromFailed

Thrown when the ERC20.transferFrom call fails.

This is an identical redefinition of SafeTransferLib.TransferFromFailed.

error TransferFromFailed();

InsufficientDeposit

Thrown when the deposit amount is less than the minimum deposit.

error InsufficientDeposit(uint96 amount, uint96 minimumDeposit);

Parameters

InsufficientBalance

Thrown when a payer has insufficient balance for a withdrawal request.

error InsufficientBalance();

ZeroWithdrawalAmount

Thrown when a withdrawal request of zero is made.

error ZeroWithdrawalAmount();

PendingWithdrawalExists

Thrown when a withdrawal is pending for a payer.

error PendingWithdrawalExists();

NoPendingWithdrawal

Thrown when a withdrawal is not pending for a payer.

error NoPendingWithdrawal();

WithdrawalNotReady

Thrown when trying to finalize a withdrawal before the withdraw lock period has passed.

error WithdrawalNotReady(uint32 timestamp, uint32 withdrawableTimestamp, uint24 nonce);

Parameters

PayerInDebt

Thrown when trying to finalize a withdrawal while in debt.

error PayerInDebt();

NoChange

Thrown when there is no change to an updated parameter.

error NoChange();

Paused

Thrown when any pausable function is called when the contract is paused.

error Paused();

NoExcess

Thrown when there is no excess fee tokens to transfer to the fee distributor.

error NoExcess();

ZeroPayer

Thrown when the payer is the zero address.

error ZeroPayer();

ZeroRecipient

Thrown when the recipient is the zero address.

error ZeroRecipient();

Structs

Payer

Represents a payer in the registry.

struct Payer {
    int104 balance;
    uint96 pendingWithdrawal;
    uint32 withdrawableTimestamp;
    uint24 withdrawalNonce;
}

Properties

PayerFee

Represents a payer and their fee.

struct PayerFee {
    address payer;
    uint96 fee;
}

Properties