PayerReportManager

Inherits: IPayerReportManager, Initializable, Migratable, ERC5267

This contract handles functionality for submitting and settling payer reports.

State Variables

PAYER_REPORT_TYPEHASH

keccak256("PayerReport(uint32 originatorNodeId,uint64 startSequenceId,uint64 endSequenceId,uint32 endMinuteSinceEpoch,bytes32 payersMerkleRoot,uint32[] nodeIds)")

bytes32 public constant PAYER_REPORT_TYPEHASH = 0x3737a2cced99bb28fc5aede45aa81d3ce0aa9137c5f417641835d0d71d303346;

ONE_HUNDRED_PERCENT

One hundred percent (in basis points).

uint16 public constant ONE_HUNDRED_PERCENT = 10_000;

parameterRegistry

The address of the parameter registry.

address public immutable parameterRegistry;

nodeRegistry

The address of the node registry.

address public immutable nodeRegistry;

payerRegistry

The address of the payer registry.

address public immutable payerRegistry;

_PAYER_REPORT_MANAGER_STORAGE_LOCATION

bytes32 internal constant _PAYER_REPORT_MANAGER_STORAGE_LOCATION =
    0x26b057ee8e4d60685198828fdf1c618ab8e36b0ab85f54a47b18319f6f718e00;

Functions

_getPayerReportManagerStorage

function _getPayerReportManagerStorage() internal pure returns (PayerReportManagerStorage storage $);

constructor

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

The parameter registry, node registry, and payer registry must not be the zero address.

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

constructor(address parameterRegistry_, address nodeRegistry_, address payerRegistry_) ERC5267();

Parameters

Name	Type	Description
`parameterRegistry_`	`address`	The address of the parameter registry.
`nodeRegistry_`	`address`	The address of the node registry.
`payerRegistry_`	`address`	The address of the payer registry.

initialize

Initializes the contract.

function initialize() public initializer;

submit

Submits a payer report.

function submit(
    uint32 originatorNodeId_,
    uint64 startSequenceId_,
    uint64 endSequenceId_,
    uint32 endMinuteSinceEpoch_,
    bytes32 payersMerkleRoot_,
    uint32[] calldata nodeIds_,
    PayerReportSignature[] calldata signatures_
) external returns (uint256 payerReportIndex_);

Parameters

Name	Type	Description
`originatorNodeId_`	`uint32`	The originator node ID.
`startSequenceId_`	`uint64`	The start sequence ID.
`endSequenceId_`	`uint64`	The end sequence ID.
`endMinuteSinceEpoch_`	`uint32`	The timestamp of the message at `endSequenceId`.
`payersMerkleRoot_`	`bytes32`	The payers Merkle root.
`nodeIds_`	`uint32[]`	The active node IDs during the reporting period.
`signatures_`	`PayerReportSignature[]`	The signature objects for the payer report.

Returns

Name	Type	Description
`payerReportIndex_`	`uint256`	The index of the payer report in the originator's payer report array.

settle

Settles a subset of a payer report.

function settle(
    uint32 originatorNodeId_,
    uint256 payerReportIndex_,
    bytes[] calldata payerFees_,
    bytes32[] calldata proofElements_
) external;

Parameters

Name	Type	Description
`originatorNodeId_`	`uint32`	The originator node ID.
`payerReportIndex_`	`uint256`	The payer report index.
`payerFees_`	`bytes[]`	The sequential payer fees to settle.
`proofElements_`	`bytes32[]`	The sequential Merkle proof elements for the payer fees to settle.

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;

updateProtocolFeeRate

Updates the protocol fee rate.

function updateProtocolFeeRate() external;

migratorParameterKey

The parameter registry key used to fetch the migrator.

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

protocolFeeRateParameterKey

The parameter registry key used to fetch the protocol fee rate.

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

protocolFeeRate

The protocol fee rate (in basis points).

function protocolFeeRate() external view returns (uint16 protocolFeeRate_);

getPayerReportDigest

Returns the EIP-712 digest for a payer report.

function getPayerReportDigest(
    uint32 originatorNodeId_,
    uint64 startSequenceId_,
    uint64 endSequenceId_,
    uint32 endMinuteSinceEpoch_,
    bytes32 payersMerkleRoot_,
    uint32[] calldata nodeIds_
) external view returns (bytes32 digest_);

Parameters

Name	Type	Description
`originatorNodeId_`	`uint32`	The originator node ID.
`startSequenceId_`	`uint64`	The start sequence ID.
`endSequenceId_`	`uint64`	The end sequence ID.
`endMinuteSinceEpoch_`	`uint32`	The timestamp of the message at `endSequenceId`.
`payersMerkleRoot_`	`bytes32`	The payers Merkle root.
`nodeIds_`	`uint32[]`	The active node IDs during the reporting period.

Returns

Name	Type	Description
`digest_`	`bytes32`	The EIP-712 digest.

getPayerReports

Returns an array of specific payer reports.

The node IDs in originatorNodeIds_ don't need to be unique.

function getPayerReports(uint32[] calldata originatorNodeIds_, uint256[] calldata payerReportIndices_)
    external
    view
    returns (PayerReport[] memory payerReports_);

Parameters

Name	Type	Description
`originatorNodeIds_`	`uint32[]`	An array of originator node IDs.
`payerReportIndices_`	`uint256[]`	An array of payer report indices for each of the respective originator node IDs.

Returns

Name	Type	Description
`payerReports_`	`PayerReport[]`	The array of payer reports.

getPayerReport

Returns a payer report.

function getPayerReport(uint32 originatorNodeId_, uint256 payerReportIndex_)
    external
    view
    returns (PayerReport memory payerReport_);

Parameters

Name	Type	Description
`originatorNodeId_`	`uint32`	The originator node ID.
`payerReportIndex_`	`uint256`	The payer report index.

Returns

Name	Type	Description
`payerReport_`	`PayerReport`	The payer report.

_name

function _name() internal pure override returns (string memory name_);

_version

function _version() internal pure override returns (string memory version_);

_getPayerReportDigest

Returns the EIP-712 digest for a payer report.

function _getPayerReportDigest(
    uint32 originatorNodeId_,
    uint64 startSequenceId_,
    uint64 endSequenceId_,
    uint32 endMinuteSinceEpoch_,
    bytes32 payersMerkleRoot_,
    uint32[] memory nodeIds_
) internal view returns (bytes32 digest_);

Parameters

Name	Type	Description
`originatorNodeId_`	`uint32`	The ID of the node originator.
`startSequenceId_`	`uint64`	The start sequence ID.
`endSequenceId_`	`uint64`	The end sequence ID.
`endMinuteSinceEpoch_`	`uint32`
`payersMerkleRoot_`	`bytes32`	The payers Merkle root.
`nodeIds_`	`uint32[]`	The active node IDs during the reporting period.

Returns

Name	Type	Description
`digest_`	`bytes32`	The EIP-712 digest.

_isZero

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

_verifyPayerReportIsUnique

Verifies that a payer report is unique, compared to a payer report at a given index.

function _verifyPayerReportIsUnique(
    uint256 lastPayerReportIndex_,
    uint32 originatorNodeId_,
    uint64 startSequenceId_,
    uint64 endSequenceId_,
    uint32 endMinuteSinceEpoch_,
    bytes32 payersMerkleRoot_,
    uint32[] calldata nodeIds_
) internal view returns (bool isUnique_);

Parameters

Name	Type	Description
`lastPayerReportIndex_`	`uint256`	The index of the last payer report.
`originatorNodeId_`	`uint32`	The originator node ID.
`startSequenceId_`	`uint64`	The start sequence ID.
`endSequenceId_`	`uint64`	The end sequence ID.
`endMinuteSinceEpoch_`	`uint32`	The timestamp of the message at `endSequenceId`.
`payersMerkleRoot_`	`bytes32`	The payers Merkle root.
`nodeIds_`	`uint32[]`	The active node IDs during the reporting period.

Returns

Name	Type	Description
`isUnique_`	`bool`	Whether the report is unique.

_verifySignatures

Verifies that enough of the signatures are valid and provided by canonical node operators and returns the array of valid signing node IDs.

function _verifySignatures(
    uint32 originatorNodeId_,
    uint64 startSequenceId_,
    uint64 endSequenceId_,
    uint32 endMinuteSinceEpoch_,
    bytes32 payersMerkleRoot_,
    uint32[] calldata nodeIds_,
    PayerReportSignature[] calldata signatures_
) internal view returns (uint32[] memory validSigningNodeIds_);

_verifySignature

Returns true if the signature is from the signer of a canonical node.

function _verifySignature(bytes32 digest_, uint32 nodeId_, bytes calldata signature_)
    internal
    view
    returns (bool isValid_);

_enforceNodeIdsMatchRegistry

function _enforceNodeIdsMatchRegistry(uint32[] calldata nodeIds_) internal view;

Structs

PayerReportManagerStorage

The UUPS storage for the payer report manager.

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

struct PayerReportManagerStorage {
    mapping(uint32 originatorId => PayerReport[] payerReports) payerReportsByOriginator;
    uint16 protocolFeeRate;
}

Properties

Name	Type	Description
`payerReportsByOriginator`	`mapping(uint32 originatorId => PayerReport[] payerReports)`	The mapping of arrays of payer reports by originator node ID.
`protocolFeeRate`	`uint16`