PP_Streaming_v1.sol

Git Source

Inherits: Module_v1, IPP_Streaming_v1

Author: Inverter Network

Manages continuous and linear streaming payment streams within the Inverter Network, allowing multiple concurrent streams per recipient. Provides tools to claim streamed amounts and manage payment schedules dynamically.

Supports complex payment interactions including streaming based on time for multiple clients and recipients, integrated with error handling for payments and managing active streaming schedules and their cancellations. DISCLAIMER: Known Limitations This contract has a known limitation that could potentially lead to a Denial of Service (DoS) attack. The activePaymentReceivers array for a client can grow unbounded, which may cause gas-intensive operations to exceed block gas limits under certain conditions. This could temporarily render some functions inoperable. While this limitation does not directly risk user funds, it may temporarily prevent users from staking, unstaking, or claiming rewards if exploited. The development team is aware of this issue and may implement a fix in future upgrades if necessary. CAUTION: Workflow deployers should be especially careful when using this payment processor with contracts that allow users to directly initiate payment streams. Such setups are particularly vulnerable to this limitation and could more easily trigger a DoS condition.

State Variables

numStreams

Provides a unique id for new payment orders added for a specific client & paymentReceiver combo. paymentClient => paymentReceiver => streamId(uint).

mapping(address => mapping(address => uint)) public numStreams;

streams

Tracks all stream details for all payment orders of a paymentReceiver for a specific paymentClient. paymentClient => paymentReceiver => streamId => Wallet.

mapping(address => mapping(address => mapping(uint => Stream))) private streams;

unclaimableStreams

Tracks all streams for payments that could not be made to the paymentReceiver due to any reason. paymentClient => token address => paymentReceiver => streamId array.

mapping(address => mapping(address => mapping(address => uint[]))) internal
    unclaimableStreams;

unclaimableAmountsForStream

Tracks all payments that could not be made to the paymentReceiver due to any reason. paymentClient => token address => paymentReceiver => streamId => unclaimable Amount.

mapping(
    address => mapping(address => mapping(address => mapping(uint => uint)))
) internal unclaimableAmountsForStream;

activePaymentReceivers

List of addresses with open payment Orders per paymentClient. paymentClient => listOfPaymentReceivers(address[]). Duplicates are not allowed.

mapping(address => address[]) private activePaymentReceivers;

activeStreams

List of streamIds of all payment orders of a particular paymentReceiver for a particular paymentClient. client => paymentReceiver => arrayOfStreamIdsWithPendingPayment(uint[]).

mapping(address => mapping(address => uint[])) private activeStreams;

defaultStart

Default start, cliff and end times for new payment orders.

uint private defaultStart;

defaultCliff

uint private defaultCliff;

defaultEnd

uint private defaultEnd;

__gap

Storage gap for future upgrades.

uint[47] private __gap;

Functions

supportsInterface

See {IERC165-supportsInterface}.

function supportsInterface(bytes4 interfaceId)
    public
    view
    virtual
    override(Module_v1)
    returns (bool);

onlyModule

Checks that the caller is an active module.

modifier onlyModule();

validClient

Checks that the client is calling for itself.

modifier validClient(address client);

activePaymentReceiver

Checks that the paymentReceiver is an active paymentReceiver.

modifier activePaymentReceiver(address client, address paymentReceiver);

init

function init(
    IOrchestrator_v1 orchestrator_,
    Metadata memory metadata,
    bytes memory configData
) external override(Module_v1) initializer;

claimAll

claim everything that the paymentClient owes to the _msgSender till the current timestamp.

This function should be callable if the _msgSender is an activePaymentReceiver.

function claimAll(address client) external;

Parameters

Name	Type	Description
client	address	The {IERC20PaymentClientBase_v1} instance address that processes all claims from _msgSender.

claimPreviouslyUnclaimable

claim every unclaimable amount that the paymentClient owes to the _msgSender and send it to a specified receiver.

This function should be callable if the _msgSender has unclaimedAmounts.

function claimPreviouslyUnclaimable(
    address client,
    address token,
    address receiver
) external;

Parameters

Name	Type	Description
client	address	The IERC20PaymentClientBase_v1 instance address that processes all claims from _msgSender.
token	address	address of the payment token.
receiver	address	The address that will receive the previously unclaimable amount.

claimForSpecificStream

claim the total amount up til block.timestamp from the client for a payment order with id = streamId by _msgSender.

If for a specific streamId, the tokens could not be transferred for some reason, it will added to the unclaimableAmounts of the paymentReceiver, and the amount would no longer hold any co-relation with he specific streamId of the paymentReceiver.

function claimForSpecificStream(address client, uint streamId) external;

Parameters

Name	Type	Description
client	address	The {IERC20PaymentClientBase_v1} instance address that processes the streamId claim from _msgSender.
streamId	uint256	The ID of the streaming payment order for which claim is being made.

processPayments

Processes all payments from an {IERC20PaymentClientBase_v1} instance. Please note: this function does not support callbacks on transfer of tokens.

It's up to the the implementation to keep up with what has been paid out or not.

function processPayments(IERC20PaymentClientBase_v1 client)
    external
    onlyModule
    validClient(address(client));

Parameters

Name	Type	Description
client	IERC20PaymentClientBase_v1	The {IERC20PaymentClientBase_v1} instance to process its to payments.

cancelRunningPayments

Cancels all unfinished payments from an {IERC20PaymentClientBase_v1} instance.

It's up to the the implementation to keep up with what has been paid out or not.

function cancelRunningPayments(IERC20PaymentClientBase_v1 client)
    external
    onlyModule
    validClient(address(client));

Parameters

Name	Type	Description
client	IERC20PaymentClientBase_v1	The {IERC20PaymentClientBase_v1} instance to process its to payments.

removeAllPaymentReceiverPayments

Deletes all payments related to a paymentReceiver & leaves currently streaming tokens in the {IERC20PaymentClientBase_v1}.

this function calls _removePayment which goes through all the payment orders for a paymentReceiver. For the payment orders that are completely streamed, their details are deleted in the _claimForSpecificStrea function and for others it is deleted in the _removePayment function only, leaving the currently streaming tokens as balance of the paymentClient itself.

function removeAllPaymentReceiverPayments(
    address client,
    address paymentReceiver
) external onlyOrchestratorAdmin;

Parameters

Name	Type	Description
client	address	The {IERC20PaymentClientBase_v1} instance address from which we will remove the payments.
paymentReceiver	address	PaymentReceiver's address.

removePaymentForSpecificStream

Deletes a specific payment with id = streamId for a paymentReceiver & leaves currently streaming tokens in the {IERC20PaymentClientBase_v1}.

the detail of the wallet that is being removed is either deleted in the _claimForSpecificStream or later down in this function itself depending on the timestamp of when this function was called.

function removePaymentForSpecificStream(
    address client,
    address paymentReceiver,
    uint streamId
) external onlyOrchestratorAdmin;

Parameters

Name	Type	Description
client	address	The {IERC20PaymentClientBase_v1} instance address from which we will remove the payment.
paymentReceiver	address	Address of the paymentReceiver whose payment order is to be removed.
streamId	uint256	The ID of the paymentReceiver's payment order which is to be removed.

isActivePaymentReceiver

Tells whether a paymentReceiver has any pending payments for a particular client.

This function is for convenience and can be easily figured out by other means in the codebase.

function isActivePaymentReceiver(address client, address paymentReceiver)
    public
    view
    returns (bool);

Parameters

Name	Type	Description
client	address	Address of the payment client.
paymentReceiver	address	Address of the paymentReceiver.

Returns

Name	Type	Description
<none>	bool	true if the paymentReceiver is active for the payment client.

startForSpecificStream

Getter for the start timestamp of a particular payment order with id = streamId associated with a particular paymentReceiver.

function startForSpecificStream(
    address client,
    address paymentReceiver,
    uint streamId
) public view returns (uint);

Parameters

Name	Type	Description
client	address	address of the payment client.
paymentReceiver	address	PaymentReceiver's address.
streamId	uint256	Id of the wallet for which start is fetched.

Returns

Name	Type	Description
<none>	uint256	start timestamp of the payment order.

cliffForSpecificStream

Getter for the cliff duration of a particular payment order with id = streamId associated with a particular paymentReceiver.

function cliffForSpecificStream(
    address client,
    address paymentReceiver,
    uint streamId
) public view returns (uint);

Parameters

Name	Type	Description
client	address	address of the payment client.
paymentReceiver	address	PaymentReceiver's address.
streamId	uint256	Id of the wallet for which cliff is fetched.

Returns

Name	Type	Description
<none>	uint256	cliff duration of the payment order.

endForSpecificStream

Getter for the stream end timestamp of a particular payment order with id = streamId associated with a particular paymentReceiver.

function endForSpecificStream(
    address client,
    address paymentReceiver,
    uint streamId
) public view returns (uint);

Parameters

Name	Type	Description
client	address	address of the payment client.
paymentReceiver	address	PaymentReceiver's address.
streamId	uint256	Id of the wallet for which end is fetched.

Returns

Name	Type	Description
<none>	uint256	end timestamp of the payment order.

releasedForSpecificStream

Getter for the amount of tokens already released for a particular payment order with id = streamId associated with a particular paymentReceiver.

function releasedForSpecificStream(
    address client,
    address paymentReceiver,
    uint streamId
) public view returns (uint);

Parameters

Name	Type	Description
client	address	address of the payment client.
paymentReceiver	address	PaymentReceiver's address.
streamId	uint256	Id of the wallet for which released is fetched.

Returns

Name	Type	Description
<none>	uint256	released amount of the payment order.

streamedAmountForSpecificStream

Calculates the amount of tokens that has already streamed for a particular payment order with id = streamId associated with a particular paymentReceiver.

function streamedAmountForSpecificStream(
    address client,
    address paymentReceiver,
    uint streamId,
    uint timestamp
) public view returns (uint);

Parameters

Name	Type	Description
client	address
paymentReceiver	address	PaymentReceiver's address.
streamId	uint256	Id of the wallet for which the streamed amount is fetched.
timestamp	uint256	the time upto which we want the streamed amount.

Returns

Name	Type	Description
<none>	uint256	streamed amount of the stream with id = streamId.

releasableForSpecificStream

Getter for the amount of releasable tokens for a particular payment order with id = streamId associated with a particular paymentReceiver.

function releasableForSpecificStream(
    address client,
    address paymentReceiver,
    uint streamId
) public view returns (uint);

Parameters

Name	Type	Description
client	address
paymentReceiver	address	PaymentReceiver's address.
streamId	uint256	Id of the wallet for which the releasable amount is fetched.

Returns

Name	Type	Description
<none>	uint256	releasable amount of the stream with id = streamId.

unclaimable

Getter for the amount of tokens that could not be claimed.

function unclaimable(address client, address token, address paymentReceiver)
    public
    view
    returns (uint amount);

Parameters

Name	Type	Description
client	address	address of the payment client.
token	address	address of the payment token.
paymentReceiver	address	PaymentReceiver's address.

Returns

Name	Type	Description
amount	uint256	Amount of tokens that could not be claimed.

viewAllPaymentOrders

See all active payment orders for a paymentClient associated with a particular paymentReceiver.

the paymentReceiver must be an active paymentReceiver for the particular payment client.

function viewAllPaymentOrders(address client, address paymentReceiver)
    external
    view
    activePaymentReceiver(client, paymentReceiver)
    returns (Stream[] memory);

Parameters

Name	Type	Description
client	address	Address of the payment client.
paymentReceiver	address	Address of the paymentReceiver.

Returns

Name	Type	Description
<none>	Stream[]	all streams for a particular payment client and payment receiver.

validPaymentOrder

Function that checks if the given PaymentOrder was valid.

function validPaymentOrder(IERC20PaymentClientBase_v1.PaymentOrder memory order)
    external
    returns (bool);

Parameters

Name	Type	Description
order	IERC20PaymentClientBase_v1.PaymentOrder	The IERC20PaymentClientBase_v1 Order that needs to be checked.

Returns

Name	Type	Description
<none>	bool	valid Bool if the Payment Order is valid.

setStreamingDefaults

function setStreamingDefaults(uint newStart_, uint newCliff_, uint newEnd_)
    external
    onlyOrchestratorAdmin;

getStreamingDefaults

function getStreamingDefaults() public view returns (uint, uint, uint);

_afterClaimCleanup

Common set of steps to be taken after everything has been claimed from a specific stream.

function _afterClaimCleanup(
    address client,
    address paymentReceiver,
    uint streamId
) internal;

Parameters

Name	Type	Description
client	address	Address of the payment client.
paymentReceiver	address	Address of the paymentReceiver.
streamId	uint256	ID of the stream that was fully claimed.

_findAddressInActiveStreams

used to find whether a particular paymentReceiver has pending payments with a client.

This function returns the first instance of the paymentReceiver address in the activePaymentReceivers[client] array, but that is completely fine as the array does not allow duplicates.

function _findAddressInActiveStreams(address client, address paymentReceiver)
    internal
    view
    returns (uint);

Parameters

Name	Type	Description
client	address	address of the payment client.
paymentReceiver	address	address of the paymentReceiver.

Returns

Name	Type	Description
<none>	uint256	uint The index of the paymentReceiver in the activePaymentReceivers[client] array. Returns type(uint256).max otherwise.

_findActiveStream

Used to find whether a particular payment order associated with a paymentReceiver and paymentClient with id = streamId is active or not.

Active means that the particular payment order is still to be paid out/claimed. This function returns the first instance of the streamId in the activeStreams[client][paymentReceiver] array, but that is fine as the array does not allow duplicates.

function _findActiveStream(
    address client,
    address paymentReceiver,
    uint streamId
) internal view returns (uint);

Parameters

Name	Type	Description
client	address	Address of the payment client.
paymentReceiver	address	Address of the paymentReceiver.
streamId	uint256	ID of the payment order that needs to be searched.

Returns

Name	Type	Description
<none>	uint256	uint The index of the paymentReceiver in the activeStreams[client][paymentReceiver] array. Returns type(uint256).max otherwise.

_cancelRunningOrders

Used to cancel all unfinished payments from the client.

All active payment orders of all active paymentReceivers associated with the client, are iterated through and their details are deleted.

function _cancelRunningOrders(address client) internal;

Parameters

Name	Type	Description
client	address	address of the payment client.

_removePayment

Deletes all payments related to a paymentReceiver & leaves currently streaming tokens in the {IERC20PaymentClientBase_v1}.

This function calls _removePayment which goes through all the payment orders for a paymentReceiver. For the payment orders that are completely streamed, their details are deleted in the _claimForSpecificStream function and for others it is deleted in the _removePayment function only, leaving the currently streaming tokens as balance of the paymentClient itself.

function _removePayment(address client, address paymentReceiver) internal;

Parameters

Name	Type	Description
client	address	Address of the payment client.
paymentReceiver	address	Address of the paymentReceiver.

_removePaymentForSpecificStream

Used to remove the payment order with id = streamId from the `activeStreams[client][paymentReceiver] array.

This function simply removes a particular payment order from the earlier mentioned array. The implications of removing a payment order from this array have to be handled outside of this function, such as checking whether the `paymentReceiver is still active or not, etc.

function _removePaymentForSpecificStream(
    address client,
    address paymentReceiver,
    uint streamId
) internal;

Parameters

Name	Type	Description
client	address	Address of the payment client.
paymentReceiver	address	Address of the paymentReceiver.
streamId	uint256	Id of the payment order that needs to be removed.

_removeStreamInformationForSpecificStream

Used to remove the stream info of the payment order with id = streamId.

This function simply removes the stream details of a particular payment order. The implications of removing the stream info of payment order have to be handled outside of this function.

function _removeStreamInformationForSpecificStream(
    address client,
    address paymentReceiver,
    uint streamId
) internal;

Parameters

Name	Type	Description
client	address	Address of the payment client.
paymentReceiver	address	Address of the paymentReceiver.
streamId	uint256	Id of the payment order whose stream information needs to be removed.

_removePaymentReceiverFromActiveStreams

Used to remove a paymentReceiver as one of the beneficiaries of the payment client

This function will be called when all the payment orders of a payment client associated with a particular paymentReceiver has been fulfilled. Also signals that the paymentReceiver is no longer an active paymentReceiver according to the payment client.

function _removePaymentReceiverFromActiveStreams(
    address client,
    address paymentReceiver
) internal;

Parameters

Name	Type	Description
client	address	Address of the payment client.
paymentReceiver	address	Address of the paymentReceiver.

_addPayment

Adds a new payment containing the details of the monetary flow depending on the module.

This function can handle multiple payment orders associated with a particular paymentReceiver for the same payment client without overriding the earlier ones. The maximum payment orders for a paymentReceiver MUST BE capped at (2**256-1).

function _addPayment(
    address _client,
    IERC20PaymentClientBase_v1.PaymentOrder memory _order,
    uint _streamId
) internal;

Parameters

Name	Type	Description
_client	address	PaymentReceiver's address.
_order	IERC20PaymentClientBase_v1.PaymentOrder	PaymentOrder that needs to be added.
_streamId	uint256	ID of the new stream of the a particular paymentReceiver being added.

_claimAll

Used to claim all the payment orders associated with a particular paymentReceiver for a given payment client.

Calls the _claimForSpecificStream function for all the active streams of a particular paymentReceiver for the given payment client. Depending on the time this function is called, the steamed payments are transferred to the paymentReceiver. For payment orders that are fully steamed, their details are deleted and changes are made to the state of the contract accordingly.

function _claimAll(address client, address paymentReceiver) internal;

Parameters

Name	Type	Description
client	address	Address of the payment client.
paymentReceiver	address	Address of the paymentReceiver for which every payment order will be claimed.

_claimForSpecificStream

Used to claim the payment order of a particular paymentReceiver for a given payment client with id = streamId.

Depending on the time this function is called, the steamed payments are transferred to the paymentReceiver or accounted in unclaimableAmounts. For payment orders that are fully steamed, their details are deleted and changes are made to the state of the contract accordingly.

function _claimForSpecificStream(
    address client,
    address paymentReceiver,
    uint streamId
) internal;

Parameters

Name	Type	Description
client	address	Address of the payment client.
paymentReceiver	address	Address of the paymentReceiver for which every payment order will be claimed.
streamId	uint256	ID of the payment order that is to be claimed.

_claimPreviouslyUnclaimable

Used to claim the unclaimable amount of a particular paymentReceiver for a given payment client.

Assumes that the streamId array is not empty.

function _claimPreviouslyUnclaimable(
    address client,
    address token,
    address paymentReceiver
) internal;

Parameters

Name	Type	Description
client	address	Address of the payment client.
token	address
paymentReceiver	address	Address of the paymentReceiver for which the unclaimable amount will be claimed.

_streamAmountForSpecificStream

Virtual implementation of the stream formula. Returns the amount steamed, as a function of time, for an asset given its total historical allocation.

function _streamAmountForSpecificStream(
    address client,
    address paymentReceiver,
    uint streamId,
    uint timestamp
) internal view virtual returns (uint);

Parameters

Name	Type	Description
client	address
paymentReceiver	address	The paymentReceiver to check on.
streamId	uint256	ID of a particular paymentReceiver's stream whose stream schedule needs to be checked.
timestamp	uint256	The time upto which we want the steamed amount.

_validPaymentReceiver

Validate address input.

function _validPaymentReceiver(address addr) internal view returns (bool);

Parameters

Name	Type	Description
addr	address	Address to validate.

Returns

Name	Type	Description
<none>	bool	True if address is valid.

_validTotal

Validate uint total amount input.

function _validTotal(uint _total) internal pure returns (bool);

Parameters

Name	Type	Description
_total	uint256	uint to validate.

Returns

Name	Type	Description
<none>	bool	True if uint is valid.

_validTimes

Validate uint start input.

function _validTimes(uint _start, uint _cliff, uint _end)
    internal
    pure
    returns (bool);

Parameters

Name	Type	Description
_start	uint256	uint to validate.
_cliff	uint256	uint to validate.
_end	uint256	uint to validate.

Returns

Name	Type	Description
<none>	bool	True if uint is valid.

_validPaymentToken

Validate payment token input.

function _validPaymentToken(address _token) internal returns (bool);

Parameters

Name	Type	Description
_token	address	Address of the token to validate.

Returns

Name	Type	Description
<none>	bool	True if address is valid.

_validOriginAndTargetChain

function _validOriginAndTargetChain(uint originChainId_, uint targetChainId_)
    internal
    view
    returns (bool);

_getStreamingDetails

function _getStreamingDetails(bytes32 flags, bytes32[] memory data)
    internal
    view
    returns (uint start, uint cliff, uint end);

_setDefaultTimes

Sets the default start time, cliff and end times for new payment orders.

function _setDefaultTimes(uint newStart_, uint newCliff_, uint newEnd_)
    internal;

Parameters

Name	Type	Description
newStart_	uint256	The new default start time.
newCliff_	uint256	The new default cliff duration.
newEnd_	uint256	The new default end time.