IPayerReportManager

Inherits: IMigratable, IERC5267, IRegistryParametersErrors, ISequentialMerkleProofsErrors

This interface exposes functionality for submitting and settling payer reports.

Functions

initialize

Initializes the contract.

function initialize() external;

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.

updateProtocolFeeRate

Updates the protocol fee rate.

function updateProtocolFeeRate() external;

PAYER_REPORT_TYPEHASH

Returns the EIP712 typehash used in the encoding of a signed digest for a payer report.

function PAYER_REPORT_TYPEHASH() external pure returns (bytes32 payerReportTypehash_);

ONE_HUNDRED_PERCENT

One hundred percent (in basis points).

function ONE_HUNDRED_PERCENT() external pure returns (uint16 oneHundredPercent_);

migratorParameterKey

The parameter registry key used to fetch the migrator.

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

protocolFeeRateParameterKey

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

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

parameterRegistry

The address of the parameter registry.

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

nodeRegistry

The address of the node registry.

function nodeRegistry() external view returns (address nodeRegistry_);

payerRegistry

The address of the payer registry.

function payerRegistry() external view returns (address payerRegistry_);

protocolFeeRate

The protocol fee rate (in basis points).

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

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.

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.

Events

PayerReportSubmitted

Emitted when a payer report is submitted.

event PayerReportSubmitted(
    uint32 indexed originatorNodeId,
    uint256 indexed payerReportIndex,
    uint64 startSequenceId,
    uint64 indexed endSequenceId,
    uint32 endMinuteSinceEpoch,
    bytes32 payersMerkleRoot,
    uint32[] nodeIds,
    uint32[] signingNodeIds
);

Parameters

Name	Type	Description
`originatorNodeId`	`uint32`	The originator node ID.
`payerReportIndex`	`uint256`	The index of the newly stored report.
`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.
`signingNodeIds`	`uint32[]`	The node IDs of the signers of the payer report.

PayerReportSubsetSettled

Emitted when a subset of a payer report is settled.

event PayerReportSubsetSettled(
    uint32 indexed originatorNodeId,
    uint256 indexed payerReportIndex,
    uint32 count,
    uint32 remaining,
    uint96 feesSettled
);

Parameters

Name	Type	Description
`originatorNodeId`	`uint32`	The originator node ID.
`payerReportIndex`	`uint256`	The payer report index.
`count`	`uint32`	The number of payer fees settled in this subset.
`remaining`	`uint32`	The number of payer fees remaining to be settled.
`feesSettled`	`uint96`	The amount of fees settled in this subset.

ProtocolFeeRateUpdated

Emitted when the protocol fee rate is updated.

event ProtocolFeeRateUpdated(uint16 protocolFeeRate);

Parameters

Name	Type	Description
`protocolFeeRate`	`uint16`	The new protocol fee rate.

Errors

ZeroParameterRegistry

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

error ZeroParameterRegistry();

ZeroNodeRegistry

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

error ZeroNodeRegistry();

ZeroPayerRegistry

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

error ZeroPayerRegistry();

InvalidStartSequenceId

Thrown when the start sequence ID is not the last end sequence ID.

error InvalidStartSequenceId(uint64 startSequenceId, uint64 lastSequenceId);

InvalidSequenceIds

Thrown when the start and end sequence IDs are invalid.

error InvalidSequenceIds();

UnorderedNodeIds

Thrown when the signing node IDs are not ordered and unique.

error UnorderedNodeIds();

InsufficientSignatures

Thrown when the number of valid signatures is insufficient.

error InsufficientSignatures(uint8 validSignatureCount, uint8 requiredSignatureCount);

PayerReportAlreadySubmitted

Thrown when the payer report has already been submitted.

error PayerReportAlreadySubmitted(uint32 originatorNodeId, uint64 startSequenceId, uint64 endSequenceId);

PayerReportIndexOutOfBounds

Thrown when the payer report index is out of bounds.

error PayerReportIndexOutOfBounds();

PayerReportEntirelySettled

Thrown when the payer report has already been entirely settled.

error PayerReportEntirelySettled();

PayerFeesLengthTooLong

Thrown when the length of the payer fees array is too long.

error PayerFeesLengthTooLong();

SettleUsageFailed

Thrown when failing to settle usage via the payer registry.

error SettleUsageFailed(bytes returnData_);

ArrayLengthMismatch

Thrown when the lengths of input arrays don't match.

error ArrayLengthMismatch();

InvalidProtocolFeeRate

Thrown when the protocol fee rate is invalid.

error InvalidProtocolFeeRate();

NoChange

Thrown when there is no change to an updated parameter.

error NoChange();

NoReportsForOriginator

Thrown when there are no payer reports found for the given originator node ID.

error NoReportsForOriginator(uint32 originatorNodeId);

Parameters

Name	Type	Description
`originatorNodeId`	`uint32`	The ID of the originator node for which no reports exist.

NodeIdsLengthMismatch

Thrown when the provided node IDs do not exactly match the registry set.

error NodeIdsLengthMismatch(uint32 expectedCount, uint32 providedCount);

NodeIdAtIndexMismatch

Element at index does not match the canonical node id at that position.

error NodeIdAtIndexMismatch(uint32 expectedId, uint32 actualId, uint32 index);

Structs

PayerReport

Represents a payer report.

struct PayerReport {
    uint64 startSequenceId;
    uint64 endSequenceId;
    uint32 endMinuteSinceEpoch;
    uint96 feesSettled;
    uint32 offset;
    bool isSettled;
    uint16 protocolFeeRate;
    bytes32 payersMerkleRoot;
    uint32[] nodeIds;
}

Properties

Name	Type	Description
`startSequenceId`	`uint64`	The start sequence ID.
`endSequenceId`	`uint64`	The end sequence ID.
`endMinuteSinceEpoch`	`uint32`	The timestamp of the message at `endSequenceId`.
`feesSettled`	`uint96`	The total fees already settled for this report.
`offset`	`uint32`	The next index in the Merkle tree that has yet to be processed/settled.
`isSettled`	`bool`	Whether the payer report is completely processed/settled.
`protocolFeeRate`	`uint16`	The portion of the fees settled that is reserved for the protocol.
`payersMerkleRoot`	`bytes32`	The payers Merkle root.
`nodeIds`	`uint32[]`	The active node IDs during the reporting period.

PayerReportSignature

Represents a payer report signature.

struct PayerReportSignature {
    uint32 nodeId;
    bytes signature;
}

Properties

Name	Type	Description
`nodeId`	`uint32`	The node ID.
`signature`	`bytes`	The signature by the node operator.